Import a bundle from a .md file, a .zip file, or pasted markdown.

POST

/bundles/import

curl --request POST \
  --url https://example.com/api/v1/bundles/import \
  --header 'Content-Type: multipart/form-data' \
  --form name=example \
  --form file=example \
  --form text=example \
  --form profile=example \
  --form files=example \
  --form docs=example \
  --form links=example

Send exactly one of file or text. In local mode, Speccy writes the bundle to a new folder named name under the folder that Speccy serves (REQ-008).

Request Body^required

Media typemultipart/form-data

object

name

The bundle folder name. The default comes from the file name or the doc title.

string

file

A .md file or a .zip file.

string

text

Pasted markdown.

string

profile

The doc type for a file that names none. Speccy writes the type line into the frontmatter of the imported file.

string

files

The files of a dropped folder. Each part’s file name is its path in the folder.

Array<string>

docs

JSON: an array of {path, profile}. The profile of each markdown file; an empty profile is not a spec.

string

links

JSON: an array of {from, to, kind}, the links a person confirmed. Speccy writes each into the from doc.

string

Responses

201

The new bundles. A folder with two or more spec docs gives one bundle per doc.

Media typeapplication/json

object

items

required

Array<object>

A folder that holds one or more spec docs and their assets.

object

id

required

string format: uuid

slug

required

The bundle folder relative to the served folder or the repo root.

string

title

required

The folder name.

string

source_kind

required

string

Allowed values: local db github

visibility

string

Allowed values: private internal link

state

required

The worst state of the bundle’s spec docs, for a list row: not_build_ready when one spec doc is Not Build Ready, then not_reviewed when one has no verdict on its current version, and build_ready only when every spec doc is Build Ready.

string

Allowed values: not_build_ready not_reviewed build_ready

docs

required

The spec docs of the bundle, by path.

Array<object>

One spec doc of a bundle, with its own profile, versions, review runs and verdict.

object

id

required

string format: uuid

bundle_id

required

The bundle that holds the spec doc.

string format: uuid

slug

required

string

title

required

string

profile_key

required

The profile of the spec doc.

string

source_kind

required

string

Allowed values: local db github

github

Where a GitHub bundle comes from, and its draft (REQ-123).

object

repo

required

string

branch

required

string

path

required

string

draft

required

The current version has changes that are not on GitHub.

boolean

ahead

required

GitHub changed after the draft started.

boolean

pr_url

string

path

required

The path of the spec doc in its bundle.

string

current_version

required

object

id

required

string format: uuid

number

required

integer format: int64

created_by

required

string

message

required

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

verdict

The verdict of the bundle’s latest completed run. It is stale when that run is not on the current version.

object

run_id

required

string format: uuid

version_number

required

integer format: int64

kind

required

Lint means only the lint stage ran.

string

Allowed values: lint full

result

required

string

Allowed values: build_ready not_build_ready stale

score

required

integer

radar

required

object

key

additional properties

integer

waiver_count

required

integer

relaxed_count

required

Checks in adoption mode (REQ-133).

integer

must

required

Open MUST findings.

integer

should

required

integer

info

required

integer

blocking_threads

Open blocking threads. Any makes the verdict Not Build Ready (§8.6 rule 2).

integer

ai_run_id

The full review whose AI findings this verdict counts. For a full run, the run itself.

string format: uuid

ai_version_number

The version the AI review read, when it is older than this verdict’s version.

integer format: int64

sections_changed

How many sections changed since the AI review read the doc.

integer

stale_reason

Set when the verdict is stale because a linked bundle has a newer version than the run read (REQ-056).

string

Allowed values: upstream_changed

stale_upstream

With stale_reason upstream_changed, the linked spec docs that have a newer version than the run read.

Array<object>

object

id

required

string format: uuid

bundle_id

required

The bundle that holds the spec doc.

string format: uuid

slug

required

string

title

required

string

profile_key

required

string

run_error

Why the latest run on the current version failed, when it failed.

string

adopt

The frontmatter keys the main doc does not name, and the values a review used for them (REQ-135). Absent when the doc names both.

object

type

string

size

string

status

string

Allowed values: draft in_review approved superseded

next_action

The one thing the caller must do next on this bundle. Absent when nothing is open. The list carries the kind and the sentence; one bundle also carries the target.

object

kind

required

string

Allowed values: waiver decide fix review adopt request_review handoff

sentence

required

What to do, in words, for a button label or a status line.

string

waiver_id

string format: uuid

finding_id

string format: uuid

tour_key

The key of the tour point to open.

string

updated_at

required

string format: date-time

next_cursor

string

problems

required

Folders that are not valid bundles, for example with two main docs (REQ-001).

Array<object>

object

path

required

string

message

required

string

Example

{
  "items": [
    {
      "source_kind": "local",
      "visibility": "private",
      "state": "not_build_ready",
      "docs": [
        {
          "source_kind": "local",
          "verdict": {
            "kind": "lint",
            "result": "build_ready",
            "stale_reason": "upstream_changed"
          },
          "status": "draft",
          "next_action": {
            "kind": "waiver"
          }
        }
      ]
    }
  ]
}

default

An error.

Media typeapplication/problem+json

RFC 9457 problem details with a stable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

instance

string

code

required

A stable machine-readable error code.

string

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "code": "example"
}