Work item

A work item is the accountable unit of work: create it with one request, then complete it with evidence when the work is accepted. Both operations return the work and its receipt. POST /work places it in the workspace Inbox when you do not provide an explicit hierarchy.

Naming crosswalk: the same record is task on the compatibility /api/entities surface. POST /work is the canonical creation operation; POST /api/v1/commands/create-work and POST /api/v1/commands/complete-work are the same handlers under their older command paths and stay callable for compatibility.

Create — `POST /api/v1/work`

Requires Authorization: Bearer oxk_... and an Idempotency-Key header (missing header returns 400 missing_idempotency_key). Unknown body fields are rejected.

Field	Type	Required	Meaning
`title`	string, 1–240	yes	The work item’s label.
`description`	string ≤4000, nullable	no	Longer body text.
`workspace_id`	UUID	no	Must match a workspace you can access; defaults to your first accessible workspace.
`initiative_id`	UUID	no*	Placement parent. *All three placement IDs must be sent together, or none.
`workstream_id`	UUID	no*	Placement parent.
`milestone_id`	UUID	no*	Placement parent. When all three are omitted, a default Inbox hierarchy is used.
`priority`	`low` `medium` `high` `urgent`	no	Defaults to `medium`.
`due_date`	date string (`YYYY-MM-DD`), nullable	no	Due date.
`metadata`	JSON object	no	Defaults to `{}`.
`estimated_cost_cents`	integer 0–100000000	no	Defaults to `0`.
`command_id`	UUID	no	Server-generated when omitted.
`causation_id`, `correlation_id`	UUID, nullable	no	Trace linkage for your own pipelines.

curl https://useorgx.com/api/v1/work \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: launch-plan-review-001' \
  -d '{
    "title": "Review the launch plan",
    "priority": "high"
  }'

Response — 201 on first write, 200 when the idempotency key replays:

{
  "data": {
    "taskId": "6f4e8a34-9f2f-4a3e-8d5b-2f1c9f7f2e1a",
    "receiptId": "7a5f9b45-0a3a-4b4f-9e6c-3a2d0a8a3f2b",
    "eventId": "8b6a0c56-1b4b-5c5a-0f7d-4b3e1b9b4a3c",
    "aggregateVersion": 1,
    "eventHash": "sha256:4f1c...",
    "duplicate": false,
    "task": { "id": "6f4e8a34-...", "title": "Review the launch plan", "status": "todo", "updated_at": "2026-08-19T14:02:07.000Z" },
    "receipt": { "id": "7a5f9b45-...", "receipt_type": "agent_run" }
  },
  "meta": { "apiVersion": "1", "workspaceId": "3d7e4f5a-...", "duplicate": false }
}

Keep data.taskId from this response. Fetch that task before completing it to obtain the current concurrency token.

Read the concurrency token

Fetch the work item before completing it. The response includes an opaque data.concurrency.version_token that preserves the server’s timestamp precision and is bound to this workspace and task.

curl https://useorgx.com/api/v1/work/6f4e8a34-9f2f-4a3e-8d5b-2f1c9f7f2e1a \
  -H "Authorization: Bearer $ORGX_API_KEY"

Copy data.concurrency.version_token exactly. Do not parse it, reformat it, or reuse it for another task.

Complete — `POST /api/v1/work/{taskId}/complete`

Same auth; Idempotency-Key header required. Send the version_token returned by the read above. The legacy expected_updated_at and expected_aggregate_version pair remains accepted during the v1 compatibility window.

Field	Type	Required	Meaning
`version_token`	opaque string	yes*	Copy from `GET /work/{taskId}`. *Preferred and required unless using the legacy pair.
`expected_updated_at`	ISO datetime with offset	no*	Legacy form; send with `expected_aggregate_version` when not using the token.
`expected_aggregate_version`	integer ≥0	no*	Legacy form; send with `expected_updated_at` when not using the token.
`summary`	string ≤4000, nullable	no	What was done.
`evidence`	JSON object	no	Proof links and structured evidence. Defaults to `{}`.
`cost_cents`	integer 0–100000000	no	Cost basis for the receipt. Defaults to `0`.
`workspace_id`	UUID	no	Must match the resolved workspace.
`causation_id`, `correlation_id`	UUID, nullable	no	Trace linkage.

curl https://useorgx.com/api/v1/work/6f4e8a34-9f2f-4a3e-8d5b-2f1c9f7f2e1a/complete \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: launch-plan-review-001-complete' \
  -d '{
    "version_token": "'$ORGX_VERSION_TOKEN'",
    "summary": "Reviewed and approved with two follow-ups.",
    "evidence": { "document_url": "https://example.com/review.md" }
  }'

Returns 202 on acceptance, 200 on idempotent replay, and 409 task_version_stale when the token no longer describes the current task. The response envelope matches creation (taskId, receiptId, eventId, aggregateVersion, duplicate, task, receipt).

All operations on this resource

Operation	Method + path	Auth	Notes
Create	`POST /api/v1/work`	API key	Canonical. `Idempotency-Key` required.
Complete	`POST /api/v1/work/{taskId}/complete`	API key	Canonical. Expectation fields required.
Create (compat)	`POST /api/v1/commands/create-work`	API key	Same handler as `POST /work`; compatibility path.
Complete (compat)	`POST /api/v1/commands/complete-work`	API key	Same handler; `task_id` in the body instead of the path.
List	`GET /api/v1/work`	API key	Cursor-paged list filtered by `status`, `initiative_id`, and `updated_since`.
Get	`GET /api/v1/work/{taskId}`	API key	Returns the work item and its concurrency token.
Update fields	`PATCH /api/entities` with `type: "task"`	API key	Title, description, priority, due date, status. `done` tasks are terminal.
Pause/resume/cancel	`POST /api/v1/lifecycle` with `level: "task"`	API key	Actions: `pause`, `resume`, `retry`, `cancel`.
Delete	Not exposed	—	Use `PATCH` status changes or `lifecycle` `cancel`. Hard delete is not part of v1.

Task status values: todo, in_progress, done, blocked. Send these exact values on writes — an unlisted value returns 400 with the valid set.

Where the IDs come from

Field you send	Obtain it from
`taskId` (path)	`POST /work` response `data.taskId`, or a compatibility task read
`expected_updated_at`	`POST /work` response `data.task.updated_at`, or a compatibility task read
`expected_aggregate_version`	`POST /work` response `data.aggregateVersion` (a fresh task is `1`)
`initiative_id`	`POST /api/v1/initiatives` response `data.initiativeId`
`workstream_id`	`POST /api/v1/initiatives` response `data.workstreamId`
`milestone_id`	`POST /api/v1/initiatives` response `data.milestoneId`
`workspace_id`	`GET /api/v1/me` → `data.default_workspace_id`; usually omit it and let the key resolve it
`receiptId` / `eventId` (returned)	Follow them in receipts and the event stream

MCP equivalents

orgx_write with a task payload uses the compatibility adapter for older clients; orgx_act drives task lifecycle transitions through MCP; orgx_inspect hydrates one task with execution context. The POST /work receipt-and-event contract has no single MCP equivalent — it is the REST-first surface.

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Create — `POST /api/v1/work`

Read the concurrency token

Complete — `POST /api/v1/work/{taskId}/complete`

All operations on this resource

Where the IDs come from

MCP equivalents

​Create — POST /api/v1/work

​Read the concurrency token

​Complete — POST /api/v1/work/{taskId}/complete

​All operations on this resource

​Where the IDs come from

​MCP equivalents

Create — `POST /api/v1/work`

Read the concurrency token

Complete — `POST /api/v1/work/{taskId}/complete`

All operations on this resource

Where the IDs come from

MCP equivalents