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.
const url = 'https://example.com/api/v1/reviews/url';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"url":"example","stages":["rubric"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/reviews/url \ --header 'Content-Type: application/json' \ --data '{ "url": "example", "stages": [ "rubric" ] }'Request Bodyrequired
Section titled “Request Bodyrequired”object
The GitHub URL of a file, a folder, a branch, a commit or a pull request.
Responses
Section titled “ Responses ”The review is queued. GET /reviews/{reviewId} gives the repo, the commit, and the review of each spec doc when it is complete.
A review that a job runs. Poll it until its status is complete or failed.
object
The stage that runs now, while the status is running.
Why the review failed, when the status is failed.
object
The app page of the report, relative to the server, such as /reviews/{id}.
The doc size the review used, from the frontmatter or inferred (REQ-134).
object
object
One failed check. The rail and the MCP tool get_findings read this one shape.
object
The last full review found this, and the full review before it did not. See Trend.
An AI finding of the last full review, which read an older version. Its section has not changed since.
The line of the file where the text of the finding starts, from 1, in the current version. 0 when the anchor is detached.
The line where the text of the finding ends.
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.
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.
The run the finding belongs to. A carried finding belongs to the last full review.
A valid waiver covers this finding (REQ-074).
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.
The check is in adoption mode, so it reports at INFO (REQ-133).
The overlay layer that shows this finding (SDD §13.2). No layer for other findings.
For a drifted code link, the commit URL a verification run reads to check the code still conforms.
For a coverage gap, the upstream trace ID it is about.
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
The slug of the linked doc.
The text of this doc that conflicts.
The text of the linked doc that it conflicts with.
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
The slug of the linked doc that must change.
Why the linked doc must change.
Waiting while the linked doc must change; sent_back after the linked doc answered that this doc must change.
The finding counts in the verdict. A waiting finding blocks only when the profile sets coherence.upstream_pending to block.
The reason of the send-back.
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.
The anchor in the bundle’s current version, re-anchored when the run read an older version.
object
Byte offset of the quote in the file.
The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).
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
The consequence class.
The two answers a builder could pick. Empty for none.
The option that fits the rest of the doc better, 1 or 2. 0 for none.
The question that asks the author to choose.
Names the one fork the finding asks about. A “Not needed” answer binds to it.
The answer the author gave on the questions screen, while its patch waits or after the author accepted it.
The option the author picked for the answer, 1 or 2, or 0 for an answer in the author’s own words.
The author answered “Not needed”, with a reason. The waiver of the answer covers this finding.
The outgoing links of the doc, as this review resolved them. A link whose target comes from an open pull request has pull.
object
The target as written. For an incoming link, the source bundle’s slug.
The linked bundle. Absent when no bundle matches the target.
object
The bundle that holds the spec doc.
Where a person opens an external target (DEC-021).
The state of an external link, as the last review run read it.
Why the link is in that state. It says what stopped an unchecked read.
When a run last read the external target.
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.
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
The number of the open pull request.
The head commit of the pull request that the review read.
The web page of the pull request.
object
The repo, as owner/name.
The commit that Speccy read.
The number of the pull request, for a pull request URL.
One reviewed spec doc. It has its review, or the reason the review of this doc stopped.
object
The folder of the doc’s bundle, relative to the repo root. The file of a finding’s anchor is relative to it.
The spec doc, relative to the repo root.
object
The app page of the report, relative to the server, such as /reviews/{id}.
The doc size the review used, from the frontmatter or inferred (REQ-134).
object
object
One failed check. The rail and the MCP tool get_findings read this one shape.
object
The last full review found this, and the full review before it did not. See Trend.
An AI finding of the last full review, which read an older version. Its section has not changed since.
The line of the file where the text of the finding starts, from 1, in the current version. 0 when the anchor is detached.
The line where the text of the finding ends.
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.
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.
The run the finding belongs to. A carried finding belongs to the last full review.
A valid waiver covers this finding (REQ-074).
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.
The check is in adoption mode, so it reports at INFO (REQ-133).
The overlay layer that shows this finding (SDD §13.2). No layer for other findings.
For a drifted code link, the commit URL a verification run reads to check the code still conforms.
For a coverage gap, the upstream trace ID it is about.
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
The slug of the linked doc.
The text of this doc that conflicts.
The text of the linked doc that it conflicts with.
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
The slug of the linked doc that must change.
Why the linked doc must change.
Waiting while the linked doc must change; sent_back after the linked doc answered that this doc must change.
The finding counts in the verdict. A waiting finding blocks only when the profile sets coherence.upstream_pending to block.
The reason of the send-back.
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.
The anchor in the bundle’s current version, re-anchored when the run read an older version.
object
Byte offset of the quote in the file.
The text changed, and Speccy cannot find the quote in the current version (SDD §8.8).
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
The consequence class.
The two answers a builder could pick. Empty for none.
The option that fits the rest of the doc better, 1 or 2. 0 for none.
The question that asks the author to choose.
Names the one fork the finding asks about. A “Not needed” answer binds to it.
The answer the author gave on the questions screen, while its patch waits or after the author accepted it.
The option the author picked for the answer, 1 or 2, or 0 for an answer in the author’s own words.
The author answered “Not needed”, with a reason. The waiver of the answer covers this finding.
The outgoing links of the doc, as this review resolved them. A link whose target comes from an open pull request has pull.
object
The target as written. For an incoming link, the source bundle’s slug.
The linked bundle. Absent when no bundle matches the target.
object
The bundle that holds the spec doc.
Where a person opens an external target (DEC-021).
The state of an external link, as the last review run read it.
Why the link is in that state. It says what stopped an unchecked read.
When a run last read the external target.
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.
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
The number of the open pull request.
The head commit of the pull request that the review read.
The web page of the pull request.
The .speccy.yaml that the review used.
object
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.
With repo, the file in the repo. With local, the file on this machine. With none, empty.
The pr section of the .speccy.yaml that the review used.
object
The most inline comments per spec doc. 0 means the default of 15.
The finding levels that go inline as comments. Empty means the default: MUST findings, and SHOULD findings with a suggestion.
None keeps the name of Speccy out of a pending review.
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" } } }}default
Section titled “default”An error.
RFC 9457 problem details with a stable code.
object
A stable machine-readable error code.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example"}