Skip to content
Speccy

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

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
docId
required
string format: uuid

The ID of one spec doc.

Request Body

Section titled “Request Body”
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

Responses

Section titled “ Responses ”

202

Section titled “202”

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.

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

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