Skip to content
Speccy

List bundles, and the folders that look like bundles but are not valid.

GET
/bundles
curl --request GET \
  --url 'https://example.com/api/v1/bundles?limit=50'

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
cursor
string
limit
integer
default: 50 >= 1 <= 100

Responses

Section titled “ Responses ”

200

Section titled “200”

One page of bundles.

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

Section titled “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
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "code": "example"
}