Skip to content
Speccy

Queue a verification of one build of this bundle against a code repo at one commit, or a folder.

POST
/docs/{docId}/verifications
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" } ] } ] }'

Parameters

Section titled “ Parameters ”

Path Parameters

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

The ID of one spec doc.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

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
target

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.

string
repo

The repo, as owner/name.

string
sha

The commit the run reads.

string
path

A folder on disk. Local mode only. A folder run has no base commit.

string
handoff_id

The handoff a builder took, when the caller names one.

string format: uuid
claims

The builder’s claims. A claim replaces the derived targets of its trace ID.

Array<object>
object
trace_id
required
string
targets
required
Array<object>
object
kind
required
string
Allowed values: code test
path
required

The file, relative to the repo root.

string
quote
required

The verbatim anchor. It must appear in the file exactly once.

string
line

The line Speccy found the quote at.

integer
holds
boolean
fault

Why the target does not hold.

string
provenance
string
Allowed values: claim literal mapper

Responses

Section titled “ Responses ”

202

Section titled “202”

The queued run. Follow its progress at /verifications/{runId}/events, or read it until its status is done or failed.

Media typeapplication/json
object
id
required
string format: uuid
doc_id
required
string format: uuid
handoff_id
string format: uuid
status
required
string
Allowed values: queued running done failed
error

Why a failed run failed.

string
verdict

The run’s own verdict, when the run is done. It is not the bundle’s Build Ready verdict.

string
Allowed values: verified not_verified
repo
required
string
sha
required
string
branch

The branch the SHA was the head of, when the target named a branch or a repo.

string
base_sha

The commit the ranking compared against. Empty when the run had no base.

string
digest

The content digest of a folder run.

string
counts
required
object
implemented
required
integer
untested
required
integer
unproven
required
integer
missing
required
integer
breached
required
integer
waived
required
integer
blocking
required
integer
skipped
required

Trace IDs outside the profile’s verify prefixes, which the gate did not verify.

integer
notes
required

The limits the scan hit.

Array<string>
stale
required

The bundle got a new version after this run.

boolean
started_by
string
created_at
required
string format: date-time
outcomes
required
Array<object>
object
trace_id
required
string
outcome
required

A test target is a citation, not a pass. Speccy runs no tests.

string
Allowed values: implemented untested unproven missing breached
level
required
string
Allowed values: MUST SHOULD INFO
blocks
required

The outcome opened a blocking thread.

boolean
waived
required
boolean
provenance
required
string
Allowed values: claim literal mapper
note
string
targets
required
Array<object>
object
kind
required
string
Allowed values: code test
path
required

The file, relative to the repo root.

string
quote
required

The verbatim anchor. It must appear in the file exactly once.

string
line

The line Speccy found the quote at.

integer
holds
boolean
fault

Why the target does not hold.

string
provenance
string
Allowed values: claim literal mapper
requirement_quote
string
code_quote
string
reason
string
Example
{
  "status": "queued",
  "verdict": "verified",
  "outcomes": [
    {
      "outcome": "implemented",
      "level": "MUST",
      "provenance": "claim",
      "targets": [
        {
          "kind": "code",
          "provenance": "claim"
        }
      ]
    }
  ]
}

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