Work API: schemas
The request and response bodies of the operations in this API.
AcceptWorkItemDto
| Property | Type | Required | Description |
|---|
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
outcomeRef | string | yes | The xema:// ref of the accepted result. |
AssignWorkItemDto
| Property | Type | Required | Description |
|---|
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
owner | WorkSubjectDto | yes | |
BlockWorkItemDto
| Property | Type | Required | Description |
|---|
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
kind | WorkBlockerKind | yes | |
note | string | no | What an external blocker waits on. |
ref | string | no | The item id or decision id (item and decision blockers). |
CreateWorkItemDto
| Property | Type | Required | Description |
|---|
contract | object | no | The execution contract: opaque JSON. |
contractKind | string | no | Names the shape of contract. |
criteria | array of string | no | The acceptance criteria, in order. |
goal | string | yes | What done looks like, in prose. Required to make the item ready. |
idempotencyKey | string | yes | Makes a retried create return the same item. |
needs | array of string (uuid) | no | Ids of items of the same project this item needs. |
owner | WorkSubjectDto | no | Defaults to the caller. |
priority | WorkItemPriority | no | |
rationale | string | no | |
title | string | yes | |
| Property | Type | Required | Description |
|---|
hasMore | boolean | yes | Whether another page exists. Mandatory for cursor pagination (§3.3). |
limit | number | no | The page size this scan was asked for. |
nextCursor | string or null | yes | Opaque continuation token, or null on the last page. Clients MUST NOT parse it, construct one, or derive meaning from its structure. |
DropWorkItemDto
| Property | Type | Required | Description |
|---|
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
reason | string | yes | |
ProblemActionableBy
Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.
Type: one of "user", "org-admin", "platform", "none"
ProblemDetailsDto
RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.
| Property | Type | Required | Description |
|---|
actionableBy | ProblemActionableBy | no | Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed. |
code | string | yes | SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name. |
detail | string | no | Human-readable and specific to THIS occurrence. |
errors | array of ProblemFieldIssueDto | no | Field-level issues, when the refusal is about the request body. |
instance | string | no | URI reference identifying the occurrence — a request path, a run, a row. |
params | map of string or number or boolean | no | Safe i18n interpolation values for the message keyed by code — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics. |
retry | ProblemRetry | no | What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known. |
status | number | yes | The HTTP status code, repeated in the body so a logged document is self-contained. |
title | string | yes | Short, human-readable, and STABLE for a given type. Never per-occurrence — that is detail. |
traceId | string | no | W3C trace-context trace-id, present when the caller sent a traceparent. Omitted rather than invented when it did not. |
type | string | yes | Absolute URI identifying the refusal TYPE. Derived one-to-one from code, so a caller may branch on either and can never be told two different things. Never about:blank. |
ProblemFieldIssueDto
| Property | Type | Required | Description |
|---|
code | string | no | SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem. |
detail | string | yes | Prose for logs and developers. A frontend localises from code + params instead. |
params | map of string or number or boolean | no | Safe i18n interpolation values for this issue's code. |
pointer | string | yes | RFC 6901 JSON Pointer into the request body. Root is "/". |
ProblemRetry
What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.
Type: one of "transient", "after-change", "never"
ReadyWorkItemDto
| Property | Type | Required | Description |
|---|
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
UnblockWorkItemDto
| Property | Type | Required | Description |
|---|
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
UpdateCriterionDto
| Property | Type | Required | Description |
|---|
evidenceRef | string | no | The xema:// ref of the evidence. |
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
met | boolean | yes | |
UpdateWorkItemDto
| Property | Type | Required | Description |
|---|
contract | object | no | |
contractKind | string | no | |
criteria | array of string | no | Replaces the criteria; met state is kept for a criterion whose text is unchanged. |
expectedRevision | number | yes | The revision of the item this change was made against; a mismatch is a 409. |
goal | string | no | |
needs | array of string (uuid) | no | Replaces the item`s needs. |
priority | WorkItemPriority | no | |
rationale | string | no | |
title | string | no | |
WorkBlockerDto
| Property | Type | Required | Description |
|---|
kind | WorkBlockerKind | yes | |
note | string or null | no | |
ref | string or null | no | |
WorkBlockerKind
Type: one of "item", "decision", "external"
WorkCriterionDto
| Property | Type | Required | Description |
|---|
evidenceRef | string or null | no | |
id | string | yes | |
met | boolean | yes | |
metAt | string (date-time) or null | no | |
metBy | WorkSubjectDto or null | no | |
position | number | yes | |
text | string | yes | |
WorkItemDto
| Property | Type | Required | Description |
|---|
blocker | WorkBlockerDto or null | no | |
contract | object or null | no | |
contractKind | string or null | no | |
createdAt | string (date-time) | yes | |
createdBy | WorkSubjectDto | yes | |
criteria | array of WorkCriterionDto | yes | |
dispatchable | boolean | yes | Ready, and every need done. Derived, never stored. |
doneAt | string (date-time) or null | no | |
dropReason | string or null | no | |
droppedAt | string (date-time) or null | no | |
frozen | boolean | yes | True once the project was deleted: the item is read-only for good. |
goal | string | yes | |
id | string | yes | |
needs | array of string | yes | Ids of the items this item needs. |
number | number | yes | The per-project handle, shown as W-<number>. |
objectRef | string | yes | The xema:// address of the item. |
outcomeRef | string or null | no | |
owner | WorkSubjectDto | yes | |
priority | WorkItemPriority | yes | |
projectId | string | yes | |
rationale | string or null | no | |
readyAt | string (date-time) or null | no | |
revision | number | yes | |
state | WorkItemState | yes | |
title | string | yes | |
updatedAt | string (date-time) | yes | |
WorkItemDtoDataEnvelope
WorkItemPriority
Type: one of "urgent", "high", "normal", "low"
WorkItemState
Type: one of "draft", "ready", "running", "waiting", "blocked", "done", "dropped"
WorkItemSummaryDto
| Property | Type | Required | Description |
|---|
createdAt | string (date-time) | yes | |
dispatchable | boolean | yes | Ready, and every need done. Derived, never stored. |
id | string | yes | |
number | number | yes | The per-project handle, shown as W-<number>. |
objectRef | string | yes | The xema:// address of the item. |
owner | WorkSubjectDto | yes | |
priority | WorkItemPriority | yes | |
projectId | string | yes | |
revision | number | yes | |
state | WorkItemState | yes | |
title | string | yes | |
updatedAt | string (date-time) | yes | |
WorkItemSummaryDtoCursorPaginatedEnvelope
WorkSubjectDto
| Property | Type | Required | Description |
|---|
id | string | yes | The user id or agent id. |
kind | WorkSubjectKind | yes | |
WorkSubjectKind
Type: one of "user", "agent"