Skip to content

Queue a review of the spec docs of a GitHub file, folder, branch, commit or pull request, at the head commit. Speccy reads the files with the GitHub credential it holds, and saves no bundle. For a pull request, it reviews the spec docs that the pull request changes.

POST
/reviews/url
curl --request POST \
--url https://example.com/api/v1/reviews/url \
--header 'Content-Type: application/json' \
--data '{ "url": "example", "stages": [ "rubric" ] }'
Media typeapplication/json
object
url
required

The GitHub URL of a file, a folder, a branch, a commit or a pull request.

string
stages
Array<string>
Allowed values: rubric grounding divergence coherence

The review is queued. GET /reviews/{reviewId} gives the repo, the commit, and the review of each spec doc when it is complete.

Media typeapplication/json

A review that a job runs. Poll it until its status is complete or failed.

object
id
required
string format: uuid
kind
required
string
Allowed values: content url
status
required
string
Allowed values: queued running complete failed
stage

The stage that runs now, while the status is running.

string
error

Why the review failed, when the status is failed.

string
content
object
id
required
string format: uuid
report_path
required

The app page of the report, relative to the server, such as /reviews/{id}.

string
size

The doc size the review used, from the frontmatter or inferred (REQ-134).

string
profile_key
required
string
profile_version
required
integer format: int64
main_doc
required
string
verdict
required
object
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
integer
must
required
integer
should
required
integer
info
required
integer
findings
required
Array<object>

One failed check. The rail and the MCP tool get_findings read this one shape.

object
new

The last full review found this, and the full review before it did not. See Trend.

boolean
carried

An AI finding of the last full review, which read an older version. Its section has not changed since.

boolean
line
required

The line of the file where the text of the finding starts, from 1, in the current version. 0 when the anchor is detached.

integer
end_line
required

The line where the text of the finding ends.

integer
fix_kind
required

Reword: the fix changes the words and no fact, so the bulk fix or an agent may fix the finding alone. answer: the fix needs a fact from the author.

string
Allowed values: reword answer
question

For an answer finding, the question that the author must answer to fix it. It names the subject and asks only for the missing fact. A finding of the divergence stage has its build question here, and one of the grounding stage has its claim.

string
run_id
required

The run the finding belongs to. A carried finding belongs to the last full review.

string format: uuid
waived
required

A valid waiver covers this finding (REQ-074).

boolean
unanswered

The reviewer gave no valid answer for this MUST check. A waiver cannot cover the finding. The next review asks for the check again, and only an answer clears it.

boolean
id
required
string format: uuid
check_slug
required
string
level
required
string
Allowed values: MUST SHOULD INFO
stage
required
string
relaxed
required

The check is in adoption mode, so it reports at INFO (REQ-133).

boolean
message
required
string
fix
string
layer

The overlay layer that shows this finding (SDD §13.2). No layer for other findings.

string
Allowed values: ambiguous unverified contradicted risk slop
verify_target

For a drifted code link, the commit URL a verification run reads to check the code still conforms.

string
trace_id

For a coverage gap, the upstream trace ID it is about.

string
conflict

One conflict between a doc and a linked doc, as a coherence.contradiction finding names it. A waiver of that check binds to it, and excuses no other conflict in the section. On a coherence.downstream-request finding, it is the conflict as the downstream doc names it.

object
with
required

The slug of the linked doc.

string
quote
required

The text of this doc that conflicts.

string
with_quote
required

The text of the linked doc that it conflicts with.

string
upstream_change

The upstream request of a coherence.contradiction finding: the answer “The linked doc must change”. While it waits, the finding reads “Waiting on” the linked doc. A send-back ends it.

object
upstream
required

The slug of the linked doc that must change.

string
upstream_title
string
reason
required

Why the linked doc must change.

string
requested_by
string
state
required

Waiting while the linked doc must change; sent_back after the linked doc answered that this doc must change.

string
Allowed values: waiting sent_back
blocks
required

The finding counts in the verdict. A waiting finding blocks only when the profile sets coherence.upstream_pending to block.

boolean
sent_back_reason

The reason of the send-back.

string
sent_back_by
string
source_url

For a missing upstream link whose target is a doc on GitHub that Speccy does not hold, the URL to add as a GitHub source.

string
anchor
required

The anchor in the bundle’s current version, re-anchored when the run read an older version.

object
file
required
string
heading_path
required
Array<string>
quote
required
string
prefix
required
string
suffix
required
string
start
required

Byte offset of the quote in the file.

integer
end
required
integer
detached

The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).

boolean
material

The materiality judge’s decision on a MUST finding. A material gap is a place where a builder who cannot ask the author must guess, and two plausible guesses differ in the data model, an interface, security or what the user sees. It blocks Build Ready. A MUST finding with class none is advice. A MUST finding with no judgement blocks.

object
class
required

The consequence class.

string
Allowed values: data_model interface security user_visible none
options

The two answers a builder could pick. Empty for none.

Array<string>
pick

The option that fits the rest of the doc better, 1 or 2. 0 for none.

integer
question

The question that asks the author to choose.

string
fork

Names the one fork the finding asks about. A “Not needed” answer binds to it.

string
answer

The answer the author gave on the questions screen, while its patch waits or after the author accepted it.

string
option

The option the author picked for the answer, 1 or 2, or 0 for an answer in the author’s own words.

integer
not_needed

The author answered “Not needed”, with a reason. The waiver of the answer covers this finding.

boolean
notes
required
Array<string>
links

The outgoing links of the doc, as this review resolved them. A link whose target comes from an open pull request has pull.

Array<object>
object
kind
required
string
Allowed values: implements refines references supersedes implemented-by
origin
required
string
Allowed values: frontmatter rule adopted breakdown
target_kind
required
string
Allowed values: bundle external
target_ref
required

The target as written. For an incoming link, the source bundle’s slug.

string
bundle

The linked bundle. Absent when no bundle matches the target.

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
target_url

Where a person opens an external target (DEC-021).

string
state

The state of an external link, as the last review run read it.

string
Allowed values: aligned drifted conflicting unchecked
state_reason

Why the link is in that state. It says what stopped an unchecked read.

string
checked_at

When a run last read the external target.

string format: date-time
removable

True when DELETE /docs/{docId}/links can remove the link: an adopted link, or a frontmatter link of a doc Speccy writes. Absent on an incoming link.

boolean
pull

Set when the target of a link rule is not in the tree and an open pull request of the same repo holds it (#142). The review read the doc at that pull request’s head commit. The doc is not merged.

object
number
required

The number of the open pull request.

integer
sha
required

The head commit of the pull request that the review read.

string
url
required

The web page of the pull request.

string
tokens_in
integer format: int64
tokens_out
integer format: int64
cost_estimate
number
cache_hits
integer
url
object
repo
required

The repo, as owner/name.

string
commit
required

The commit that Speccy read.

string
pull

The number of the pull request, for a pull request URL.

integer
docs
required
Array<object>

One reviewed spec doc. It has its review, or the reason the review of this doc stopped.

object
slug
required
string
dir
required

The folder of the doc’s bundle, relative to the repo root. The file of a finding’s anchor is relative to it.

string
path
required

The spec doc, relative to the repo root.

string
review
object
id
required
string format: uuid
report_path
required

The app page of the report, relative to the server, such as /reviews/{id}.

string
size

The doc size the review used, from the frontmatter or inferred (REQ-134).

string
profile_key
required
string
profile_version
required
integer format: int64
main_doc
required
string
verdict
required
object
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
integer
must
required
integer
should
required
integer
info
required
integer
findings
required
Array<object>

One failed check. The rail and the MCP tool get_findings read this one shape.

object
new

The last full review found this, and the full review before it did not. See Trend.

boolean
carried

An AI finding of the last full review, which read an older version. Its section has not changed since.

boolean
line
required

The line of the file where the text of the finding starts, from 1, in the current version. 0 when the anchor is detached.

integer
end_line
required

The line where the text of the finding ends.

integer
fix_kind
required

Reword: the fix changes the words and no fact, so the bulk fix or an agent may fix the finding alone. answer: the fix needs a fact from the author.

string
Allowed values: reword answer
question

For an answer finding, the question that the author must answer to fix it. It names the subject and asks only for the missing fact. A finding of the divergence stage has its build question here, and one of the grounding stage has its claim.

string
run_id
required

The run the finding belongs to. A carried finding belongs to the last full review.

string format: uuid
waived
required

A valid waiver covers this finding (REQ-074).

boolean
unanswered

The reviewer gave no valid answer for this MUST check. A waiver cannot cover the finding. The next review asks for the check again, and only an answer clears it.

boolean
id
required
string format: uuid
check_slug
required
string
level
required
string
Allowed values: MUST SHOULD INFO
stage
required
string
relaxed
required

The check is in adoption mode, so it reports at INFO (REQ-133).

boolean
message
required
string
fix
string
layer

The overlay layer that shows this finding (SDD §13.2). No layer for other findings.

string
Allowed values: ambiguous unverified contradicted risk slop
verify_target

For a drifted code link, the commit URL a verification run reads to check the code still conforms.

string
trace_id

For a coverage gap, the upstream trace ID it is about.

string
conflict

One conflict between a doc and a linked doc, as a coherence.contradiction finding names it. A waiver of that check binds to it, and excuses no other conflict in the section. On a coherence.downstream-request finding, it is the conflict as the downstream doc names it.

object
with
required

The slug of the linked doc.

string
quote
required

The text of this doc that conflicts.

string
with_quote
required

The text of the linked doc that it conflicts with.

string
upstream_change

The upstream request of a coherence.contradiction finding: the answer “The linked doc must change”. While it waits, the finding reads “Waiting on” the linked doc. A send-back ends it.

object
upstream
required

The slug of the linked doc that must change.

string
upstream_title
string
reason
required

Why the linked doc must change.

string
requested_by
string
state
required

Waiting while the linked doc must change; sent_back after the linked doc answered that this doc must change.

string
Allowed values: waiting sent_back
blocks
required

The finding counts in the verdict. A waiting finding blocks only when the profile sets coherence.upstream_pending to block.

boolean
sent_back_reason

The reason of the send-back.

string
sent_back_by
string
source_url

For a missing upstream link whose target is a doc on GitHub that Speccy does not hold, the URL to add as a GitHub source.

string
anchor
required

The anchor in the bundle’s current version, re-anchored when the run read an older version.

object
file
required
string
heading_path
required
Array<string>
quote
required
string
prefix
required
string
suffix
required
string
start
required

Byte offset of the quote in the file.

integer
end
required
integer
detached

The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).

boolean
material

The materiality judge’s decision on a MUST finding. A material gap is a place where a builder who cannot ask the author must guess, and two plausible guesses differ in the data model, an interface, security or what the user sees. It blocks Build Ready. A MUST finding with class none is advice. A MUST finding with no judgement blocks.

object
class
required

The consequence class.

string
Allowed values: data_model interface security user_visible none
options

The two answers a builder could pick. Empty for none.

Array<string>
pick

The option that fits the rest of the doc better, 1 or 2. 0 for none.

integer
question

The question that asks the author to choose.

string
fork

Names the one fork the finding asks about. A “Not needed” answer binds to it.

string
answer

The answer the author gave on the questions screen, while its patch waits or after the author accepted it.

string
option

The option the author picked for the answer, 1 or 2, or 0 for an answer in the author’s own words.

integer
not_needed

The author answered “Not needed”, with a reason. The waiver of the answer covers this finding.

boolean
notes
required
Array<string>
links

The outgoing links of the doc, as this review resolved them. A link whose target comes from an open pull request has pull.

Array<object>
object
kind
required
string
Allowed values: implements refines references supersedes implemented-by
origin
required
string
Allowed values: frontmatter rule adopted breakdown
target_kind
required
string
Allowed values: bundle external
target_ref
required

The target as written. For an incoming link, the source bundle’s slug.

string
bundle

The linked bundle. Absent when no bundle matches the target.

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
target_url

Where a person opens an external target (DEC-021).

string
state

The state of an external link, as the last review run read it.

string
Allowed values: aligned drifted conflicting unchecked
state_reason

Why the link is in that state. It says what stopped an unchecked read.

string
checked_at

When a run last read the external target.

string format: date-time
removable

True when DELETE /docs/{docId}/links can remove the link: an adopted link, or a frontmatter link of a doc Speccy writes. Absent on an incoming link.

boolean
pull

Set when the target of a link rule is not in the tree and an open pull request of the same repo holds it (#142). The review read the doc at that pull request’s head commit. The doc is not merged.

object
number
required

The number of the open pull request.

integer
sha
required

The head commit of the pull request that the review read.

string
url
required

The web page of the pull request.

string
tokens_in
integer format: int64
tokens_out
integer format: int64
cost_estimate
number
cache_hits
integer
error
string
config
required

The .speccy.yaml that the review used.

object
source
required

Repo: the .speccy.yaml of the repo at the commit. local: the .speccy.yaml of the folder that this Speccy serves, because the repo has none at the commit. none: the repo and the folder have none.

string
Allowed values: repo local none
path
required

With repo, the file in the repo. With local, the file on this machine. With none, empty.

string
pr
required

The pr section of the .speccy.yaml that the review used.

object
inline_limit
required

The most inline comments per spec doc. 0 means the default of 15.

integer
levels
required

The finding levels that go inline as comments. Empty means the default: MUST findings, and SHOULD findings with a suggestion.

Array<string>
Allowed values: must should
attribution
required

None keeps the name of Speccy out of a pending review.

string
Allowed values: speccy none
created_at
required
string format: date-time
Example
{
"kind": "content",
"status": "queued",
"content": {
"verdict": {
"result": "build_ready"
},
"findings": [
{
"fix_kind": "reword",
"level": "MUST",
"layer": "ambiguous",
"upstream_change": {
"state": "waiting"
},
"material": {
"class": "data_model"
}
}
],
"links": [
{
"kind": "implements",
"origin": "frontmatter",
"target_kind": "bundle",
"state": "aligned"
}
]
},
"url": {
"docs": [
{
"review": {
"verdict": {
"result": "build_ready"
},
"findings": [
{
"fix_kind": "reword",
"level": "MUST",
"layer": "ambiguous",
"upstream_change": {
"state": "waiting"
},
"material": {
"class": "data_model"
}
}
],
"links": [
{
"kind": "implements",
"origin": "frontmatter",
"target_kind": "bundle",
"state": "aligned"
}
]
}
}
],
"config": {
"source": "repo",
"pr": {
"levels": [
"must"
],
"attribution": "speccy"
}
}
}
}

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