Skip to content
Speccy

Report what the build learned about the doc (REQ-137). A blocked report opens a blocking thread.

POST
/handoffs/{handoffId}/report
curl --request POST \
  --url https://example.com/api/v1/handoffs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/report \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "blocked", "section": [ "example" ], "trace_id": "example", "text": "example" }'

Parameters

Section titled “ Parameters ”

Path Parameters

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

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

What a coding agent learned about the doc while it built from it (REQ-137).

object
kind
required

Blocked means the agent cannot build the section without an answer. note means it built something, and the doc was unclear.

string
Allowed values: blocked note
section

The heading path of the section the report is about.

Array<string>
trace_id

A trace ID the report is about, such as REQ-012. Speccy anchors the thread to where the doc defines it.

string
text
required

What the agent needs, in its own words.

string

Responses

Section titled “ Responses ”

200

Section titled “200”

The thread the report opened.

Media typeapplication/json
object
id
required
string format: uuid
doc_id
string format: uuid
profile_key
string
anchor_kind
required
string
Allowed values: text section finding check
anchor
required

For text, an Anchor. For a section, {heading_path}. For a finding, {finding_id, check_slug}. For a check, {check_slug}.

object
key
additional properties
any
addressed_to
required
string
Allowed values: humans ai
title
required
string
handoff_id

The handoff a builder opened this thread from (REQ-137).

string format: uuid
handoff_version

The bundle version the builder took. 0 when no handoff opened it.

integer format: int64
blocking
required
boolean
status
required
string
Allowed values: open resolved
created_by
required
string
created_at
required
string format: date-time
last_message_at
required
string format: date-time
message_count
required
integer
messages
required
Array<object>
object
id
required
string format: uuid
seq
required
integer
author_kind
required
string
Allowed values: user guest ai
author_id
string
author_name
required
string
body
required
string
sources
required
Array<string>
decision
required
string
Allowed values: "" decision reversal
created_at
required
string format: date-time
answering
required

The AI is writing an answer.

boolean
Example
{
  "anchor_kind": "text",
  "addressed_to": "humans",
  "status": "open",
  "messages": [
    {
      "author_kind": "user",
      "decision": ""
    }
  ]
}

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