Skip to content

Propose a new breakdown of the doc's current version. A doc that is not Build Ready is refused, unless acknowledged. It replaces a breakdown that has no pushed issue.

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

The ID of one spec doc.

Media typeapplication/json
object
acknowledged

Propose it from a doc that is not Build Ready. The breakdown stores the verdict.

boolean
Examplegenerated
{
"acknowledged": true
}

The proposed breakdown.

Media typeapplication/json

The epics and work items Speccy proposed from one Build Ready doc. One per doc. It moves forward with the doc’s versions.

object
id
required
string format: uuid
doc_id
required
string format: uuid
bundle
required
string
title
required
string
version_number
required

The doc version the breakdown quotes.

integer format: int64
current_version_number
required
integer format: int64
stale
required

The doc has a newer version than the one the breakdown quotes.

boolean
verdict
required

The verdict the breakdown was taken at.

string
acknowledged
required

The breakdown was taken from a doc that was not Build Ready.

boolean
revision
required

Pass it as based_on with an edit.

integer format: int64
epics
required
Array<object>
object
id
required
string
title
required
string
default_assignee
object
kind
required
string
Allowed values: person agent
id
required

The tracker’s ID for the person or the agent.

string
name
required
string
issue
object
tracker
required
string
Allowed values: linear jira github
key
required
string
url
required
string
handoff_id
required
string format: uuid
version_number
required

The doc version the issue was pushed from.

integer format: int64
created_at
required
string format: date-time
items
required
Array<object>
object
id
required
string
ref
required

Bundle/item, which get_work_item takes.

string
epic
required
string
title
required
string
trace_ids
required
Array<string>
heading_path
required

The section the item is anchored on, when the doc has no trace IDs.

Array<string>
criteria
required
Array<object>
object
quote
required
string
heading_path
required
Array<string>
trace_id
string
doc

The slug of the linked spec doc the quote comes from. Absent for this doc.

string
answers
required

The agreed build answers for the item’s trace IDs and sections.

Array<object>
object
question
required
string
answer
required
string
repos
required
Array<string>
depends_on
required
Array<string>
questions
required
Array<string>
note
string
assignee
object
kind
required
string
Allowed values: person agent
id
required

The tracker’s ID for the person or the agent.

string
name
required
string
effective_assignee
object
kind
required
string
Allowed values: person agent
id
required

The tracker’s ID for the person or the agent.

string
name
required
string
changed
required

What a newer doc version changed in this item.

Array<string>
readers
object
diverge
required
boolean
readings
required
Array<string>
reason
required
string
current
required

False when the item changed after the readers read it.

boolean
issue
object
tracker
required
string
Allowed values: linear jira github
key
required
string
url
required
string
handoff_id
required
string format: uuid
version_number
required

The doc version the issue was pushed from.

integer format: int64
created_at
required
string format: date-time
covered
required

The trace IDs a person said need no work item.

Array<object>
object
trace_id
required
string
answer
required
string
Allowed values: out_of_scope covered_elsewhere no_build
reason
required
string
by
required
string
findings
required
Array<object>
object
slug
required
string
level
required
string
Allowed values: MUST SHOULD INFO
message
required
string
items
required
Array<string>
trace_id
string
coverage
required

Each trace ID of the doc, with the items that hold it.

Array<object>
object
trace_id
required
string
text
required
string
items
required
Array<string>
cover

The answer that says the trace ID needs no item.

string
new_trace_ids
required

The trace IDs a newer doc version added. Empty when the breakdown is not stale.

Array<string>
must
required

The MUST findings. A push is refused while it is above 0.

integer
cover_answers
required

The answers that close a coverage finding.

Array<string>
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
"epics": [
{
"default_assignee": {
"kind": "person"
},
"issue": {
"tracker": "linear"
}
}
],
"items": [
{
"assignee": {
"kind": "person"
},
"effective_assignee": {
"kind": "person"
},
"issue": {
"tracker": "linear"
}
}
],
"covered": [
{
"answer": "out_of_scope"
}
],
"findings": [
{
"level": "MUST"
}
]
}

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