Create the unpushed epics and work items as tracker issues. Refused while the breakdown has a MUST finding or is stale. It never edits or closes an issue, and records one handoff with the label breakdown.
const url = 'https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/breakdown/push';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"based_on":1,"tracker":"linear","target":"example","acknowledged":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/breakdown/push \ --header 'Content-Type: application/json' \ --data '{ "based_on": 1, "tracker": "linear", "target": "example", "acknowledged": true }'Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”The ID of one spec doc.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The Linear team, the Jira project URL, or the GitHub repo as owner/name.
Push from a doc that is not Build Ready. The handoff stores the verdict.
Responses
Section titled “ Responses ”What the push created.
object
The handoff the push recorded, with the label breakdown. Empty when nothing was new.
The issues this push created. Empty when every item was already pushed.
object
The epics and work items Speccy proposed from one Build Ready doc. One per doc. It moves forward with the doc’s versions.
object
The doc version the breakdown quotes.
The doc has a newer version than the one the breakdown quotes.
The verdict the breakdown was taken at.
The breakdown was taken from a doc that was not Build Ready.
Pass it as based_on with an edit.
object
object
The tracker’s ID for the person or the agent.
object
The doc version the issue was pushed from.
object
Bundle/item, which get_work_item takes.
The section the item is anchored on, when the doc has no trace IDs.
object
The slug of the linked spec doc the quote comes from. Absent for this doc.
The agreed build answers for the item’s trace IDs and sections.
object
object
The tracker’s ID for the person or the agent.
object
The tracker’s ID for the person or the agent.
What a newer doc version changed in this item.
object
False when the item changed after the readers read it.
object
The doc version the issue was pushed from.
The trace IDs a person said need no work item.
object
object
Each trace ID of the doc, with the items that hold it.
object
The answer that says the trace ID needs no item.
The trace IDs a newer doc version added. Empty when the breakdown is not stale.
The MUST findings. A push is refused while it is above 0.
The answers that close a coverage finding.
Example
{ "created": [ { "kind": "epic" } ], "breakdown": { "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" } ] }}default
Section titled “default”An error.
RFC 9457 problem details with a stable code.
object
A stable machine-readable error code.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example"}