Skip to content

The slice of the spec one work item builds, at the version it was pushed from.

GET
/work-items
curl --request GET \
--url 'https://example.com/api/v1/work-items?ref=example'
ref
required
string

The work item’s Speccy URL, its tracker issue URL or key, or bundle/item.

The work item packet.

Media typeapplication/json

The slice of the spec one work item builds. A builder reads it.

object
bundle
required
string
doc_id
required
string format: uuid
item
required
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
version_number
required

The doc version the item was pushed from, or the breakdown’s version for an unpushed item.

integer format: int64
current_version_number
required
integer format: int64
newer_version
required

The doc has a newer version than the pinned one. Ask the author before building from it.

boolean
handoff_id
string format: uuid
verdict

The verdict at the handoff.

string
main_doc
required
string
doc
required

The doc text at the pinned version.

string
links
required
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
external_links
required
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
Example
{
"item": {
"assignee": {
"kind": "person"
},
"effective_assignee": {
"kind": "person"
},
"issue": {
"tracker": "linear"
}
}
}

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