Queue a verification of one build of this bundle against a code repo at one commit, or a folder.
const url = 'https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/verifications';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"target":"example","repo":"example","sha":"example","path":"example","handoff_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","claims":[{"trace_id":"example","targets":[{"kind":"code","path":"example","quote":"example","line":1,"holds":true,"fault":"example","provenance":"claim"}]}],"trace_ids":["example"],"work_item":"example"}'};
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/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/verifications \ --header 'Content-Type: application/json' \ --data '{ "target": "example", "repo": "example", "sha": "example", "path": "example", "handoff_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "claims": [ { "trace_id": "example", "targets": [ { "kind": "code", "path": "example", "quote": "example", "line": 1, "holds": true, "fault": "example", "provenance": "claim" } ] } ], "trace_ids": [ "example" ], "work_item": "example" }'Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”The ID of one spec doc.
Request Bodyrequired
Section titled “Request Bodyrequired”The code target of one verification run: a pasted target, a GitHub repo and a commit, or a folder on disk. With none, the run reads the bundle’s implemented-by link.
object
A GitHub URL of a repo, a branch, a file, a commit or a pull request, or owner/name. In local mode, also an absolute folder path.
The repo, as owner/name.
The commit the run reads.
A folder on disk. Local mode only. A folder run has no base commit.
The handoff a builder took, when the caller names one.
The builder’s claims. A claim replaces the derived targets of its trace ID.
object
object
The file, relative to the repo root.
The verbatim anchor. It must appear in the file exactly once.
The line Speccy found the quote at.
Why the target does not hold.
Scope the run to these trace IDs. The run gives outcomes and opens blocking threads for these IDs only. Empty or absent verifies every trace ID.
Scope the run to the trace IDs of one work item, named by its tracker issue URL or key, its Speccy URL, or bundle/item.
Responses
Section titled “ Responses ”The queued run. Follow its progress at /verifications/{runId}/events, or read it until its status is done or failed.
object
Why a failed run failed.
The run’s own verdict, when the run is done. It is not the bundle’s Build Ready verdict.
The branch the SHA was the head of, when the target named a branch or a repo.
The commit the ranking compared against. Empty when the run had no base.
The content digest of a folder run.
object
Trace IDs outside the profile’s verify prefixes, which the gate did not verify.
The limits the scan hit.
The bundle got a new version after this run.
The trace IDs the run was scoped to. Empty when it verified every trace ID.
The work item the run was scoped to, as bundle/item.
The run read the head of a pull request. It opens no blocking thread and does not count toward the handoff.
object
A test target is a citation, not a pass. Speccy runs no tests.
The outcome opened a blocking thread.
object
The file, relative to the repo root.
The verbatim anchor. It must appear in the file exactly once.
The line Speccy found the quote at.
Why the target does not hold.
Example
{ "status": "queued", "verdict": "verified", "outcomes": [ { "outcome": "implemented", "level": "MUST", "provenance": "claim", "targets": [ { "kind": "code", "provenance": "claim" } ] } ]}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"}