Skip to content
Speccy

Take the build packet of a Build Ready bundle, and record the handoff (REQ-136).

POST
/docs/{docId}/handoff
curl --request POST \
  --url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/handoff \
  --header 'Content-Type: application/json' \
  --data '{ "acknowledged": true, "label": "example" }'

Parameters

Section titled “ Parameters ”

Path Parameters

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

The ID of one spec doc.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
acknowledged

Take the packet although the verdict is not Build Ready, or is stale. The handoff records the verdict it was taken at.

boolean
label

What the builder calls this work, such as a repo, a branch, or a ticket.

string
Examplegenerated
{
  "acknowledged": true,
  "label": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The build packet.

Media typeapplication/json

What a coding agent needs to build one bundle (REQ-136).

object
handoff_id
required
string format: uuid
bundle
required

The bundle slug.

string
title
required
string
version_number
required
integer format: int64
main_doc
required

The path of the main doc inside files.

string
files
required

The main doc and its assets.

Array<object>
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
external_links
required

The issues, pages, and code this doc links to (DEC-021). Speccy fetches no content for them.

Array<object>
object
kind
required
string
ref
required

The target as the doc writes it, such as github:acme/app#internal/pay.

string
url
required
string
commit

For a code target, the commit the last review run read.

string
links
required

The main doc of each bundle this one links to.

Array<object>
object
kind
required
string
bundle
required
string
title
required
string
path
required

The path the packet writes it at, such as links/payments-prd.md.

string
content
required
string
trace_ids
required
Array<object>
object
id
required
string
text
required

The line that defines the ID.

string
questions
required
Array<object>
object
number
required
integer
text
required
string
result
required
string
Allowed values: agree diverge gap
answer

The answer the readers agreed on. Absent when they diverged, or when nobody could answer.

string
handoff_md
required

The re-entry prompt, as markdown. The agent owns it after the handoff.

string
Example
{
  "files": [
    {
      "encoding": "text"
    }
  ],
  "questions": [
    {
      "result": "agree"
    }
  ]
}

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