Skip to content

List the findings of a run, in document order.

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

The findings.

Media typeapplication/json
object
items
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
Example
{
"items": [
{
"fix_kind": "reword",
"level": "MUST",
"layer": "ambiguous",
"upstream_change": {
"state": "waiting"
},
"material": {
"class": "data_model"
}
}
]
}

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