Skip to content
Speccy

Review bundle files that are not saved on the server (SDD §12.2 --server, REQ-111 review_content). The server keeps the files and the result for 90 days for the report (SDD §12.4); it changes no bundle.

POST
/reviews
curl --request POST \
  --url https://example.com/api/v1/reviews \
  --header 'Content-Type: application/json' \
  --data '{ "slug": "example", "main_doc": "example", "profile": "example", "stages": [ "rubric" ], "files": [ { "path": "example", "content": "example", "encoding": "text" } ] }'

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
slug

The bundle’s slug. Links from other bundles and to this one use it.

string
main_doc

The main doc of a single-file bundle (REQ-001 form b). Absent means the one file with a type in its frontmatter.

string
profile

The profile for a main doc with no type in its frontmatter (REQ-130).

string
stages
Array<string>
Allowed values: rubric grounding divergence coherence
files
required
Array<object>
>= 1 items <= 500 items
object
path
required

The path in the bundle.

string
content
required

The file text, or base64 when encoding is base64.

string
encoding
string
Allowed values: text base64

Responses

Section titled “ Responses ”

200

Section titled “200”

The findings and the verdict.

Media typeapplication/json
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>
object
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
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
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
notes
required
Array<string>
tokens_in
integer format: int64
tokens_out
integer format: int64
cost_estimate
number
cache_hits
integer
Example
{
  "verdict": {
    "result": "build_ready"
  },
  "findings": [
    {
      "level": "MUST",
      "layer": "ambiguous"
    }
  ]
}

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