Skip to content

Start a full review of the current version (REQ-020). Lint runs on its own on every save.

POST
/docs/{docId}/runs
curl --request POST \
--url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/runs \
--header 'Content-Type: application/json' \
--data '{ "stages": [ "rubric" ] }'
docId
required
string format: uuid

The ID of one spec doc.

Media typeapplication/json
object
stages

The model stages to run. Absent means all. Lint and the verdict always run.

Array<string>
Allowed values: rubric grounding divergence coherence

The queued run. Follow its progress at /runs/{runId}/events.

Media typeapplication/json
object
id
required
string format: uuid
doc_id
required
string format: uuid
version_id
required
string format: uuid
version_number
required
integer format: int64
profile_key
required
string
profile_version
required
integer format: int64
kind
required
string
Allowed values: lint full
status
required
string
Allowed values: queued running complete failed
stage
required
string
error
required
string
started_at
required
string format: date-time
finished_at
string format: date-time
tokens_in
integer format: int64
tokens_out
integer format: int64
cost_estimate

USD, from the prices on the role assignments.

number
cache_hits

Steps answered from the cache (REQ-021).

integer format: int64
notes

Notes for the run report, such as “no search source configured” (REQ-034).

Array<string>
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
Example
{
"kind": "lint",
"status": "queued",
"verdict": {
"kind": "lint",
"result": "build_ready",
"stale_reason": "upstream_changed"
}
}

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