Skip to content

Get one spec doc.

GET
/docs/{docId}
curl --request GET \
--url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0
docId
required
string format: uuid

The ID of one spec doc.

The spec doc.

Media typeapplication/json

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
local_dir

For a local bundle, the folder on disk that holds the bundle’s files. A coding agent edits the files there.

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 that block the verdict. A MUST finding that the materiality judge called no material gap counts as SHOULD, because it is advice.

integer
unanswered

The MUST findings of checks that came back with no answer. They count in must. Another review answers them, so they are not questions.

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
trend

What the last full review fixed, left open and found new, against the full review before it. The unit is a check in a section, or a build question; only open MUST and SHOULD findings count. Absent when the doc has one full review or none.

object
since_version
required

The version that the earlier full review read.

integer format: int64
fixed
required
integer
open
required
integer
new
required
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

Questions opens the questions screen, with everything that blocks Build Ready and needs the author. breakdown opens the breakdown screen of an app or initiative doc, in place of handoff. verify opens the verify field, after a handoff with no usable verification run.

string
Allowed values: waiver questions review adopt request_review handoff breakdown verify
sentence
required

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

string
waiver_id
string format: uuid
Example
{
"source_kind": "local",
"verdict": {
"kind": "lint",
"result": "build_ready",
"stale_reason": "upstream_changed"
},
"status": "draft",
"next_action": {
"kind": "waiver"
}
}

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"
}