Filing, reading and changing work items

This page lists the board's routes for filing, reading and changing a work item. The routes that decide a gate, pause, resume, skip, escalate, end and retry an item are on Gates, run control, ending and retry. The shapes the routes answer with are on The work item object.

Every route under /api/ except the stable routes, and the /api/ws/events WebSocket, exists for the board and can change in any release. For those, prefer the kraft command with --json, which is stable.

Routes that read an item's budget, events, diff and documents are on Budget, events, diff and documents.

Filing a work item

POST /api/work-items

Files a work item. The item is paused unless the body sets autostart: true, like kraft item create without --autostart. POST /api/work-items?dry_run=1 runs the same checks and files nothing: see Dry run.

A POST or PATCH body naming two different chains under chain and chain_template is refused with 422, its detail one sentence naming both. The same chain twice is fine.

The answer is 201 with {"id": "...", "status": "paused"} for an item filed paused, and also when autostart: true found every slot busy. These keys appear only when they apply:

An item that starts at once answers 201 with bead_id, chain_definition, materialized_chain and current_node_id beside id and status.

The server cannot tell a coding agent that runs kraft item create --autostart in its own shell from a person, so that call starts the item.

Every repo path you send must be absolute: the server would read a relative one against its own directory, not yours. POST /api/work-items, POST /api/repos and POST /api/triggers refuse a relative path with 422, and PATCH or DELETE /api/repos?path= answer 404.

POST /api/work-items/{id}/duplicate

Files a fresh, paused item from the item {id}: its title, description, repo, chain, workspace selection and attachments, snapshotted again under the new item's own id. Any source status is accepted, archived and cancelled included. No run state, override, policy override, budget or bead link carries over. This is a fresh intake, not a clone of the row. Agent review of the item's auto_escalate gates is armed, as for an ordinary create, whatever the source had. The body is empty.

{"id": "...", "status": "paused", "duplicate_warning": "..."}

duplicate_warning is present only when another open item looks like a duplicate, the same check POST /api/work-items makes.

Reading work items

GET /api/work-items

Answers the board: {"items": [...], "cursor": N}. cursor is the highest event seq at the time of the read. Each row is the list row: a short subset of the item's fields, with display_status, stop (without facts, task and attempt), step, mr_ref and progress (without tasks) in place of the detail's per-row lookups. It carries no agent_overrides, node_overrides or policy_override.

GET /api/work-items/{id}

Answers one item as the detail object, and 404 for an id that names no item.

Changing a work item

PATCH /api/work-items/{id}

Changes the fields the body names and leaves the rest. A body naming none is refused with 422. The write is one transaction, so a body that changes several fields never lands half.

agent_overrides replaces the override as a whole. A field you leave out, or send as null, is dropped, and {} clears the override.

node_overrides merges per node. {"plan": {"effort": "high"}} sets that field and keeps the node's others, {"plan": {"effort": null}} drops one field, and {"plan": {}} drops the node's overrides. {} resets every node.

The answer is {"id": "...", ...} with each field you sent. A chain you sent is echoed as chain_template. agent_overrides and node_overrides are echoed as stored: {} once an override is cleared, and for node_overrides only the nodes you named.

A started node accepts one exception. On an item stopped at that node because its stored model or escalate_model is not a model id, clearing that node ({"<node>": {}}) and changing model, escalate_model or effort alone are accepted, so the stop can be repaired.

POST /api/work-items/bulk

Applies one action to several items, each through the single-item route, in ids order, each in its own write.

{"action": "pause", "ids": ["...", "..."], "reason": "..."}

The answer is one result per id, in order:

{"results": [{"id": "...", "ok": true, "status": "paused"}, {"id": "...", "ok": false, "error": "..."}]}

An id whose action raises, an item in the wrong status for example, becomes {id, ok: false, error, status}, and the rest of the batch still runs. An id that names no item answers {id, ok: false, error: "not found"} with no status. status is the item's stored status after the action ran.

Related

• Gates, run control, ending and retry: the routes that decide, pause, resume, skip, escalate, end and retry an item.
• The work item object: the stored row, the list row and the detail object these routes answer with.
• Item verbs: the kraft item command behind each action here, with its flags and output.
• MCP tools: which of these an agent may call on its own item.
• Agents and gates: why a worker session is refused some of these, and what that check does not stop.