> ## Documentation Index > Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Work item > The task resource behind POST /work and POST /work/{taskId}/complete — wire fields, versions, and where every referenced ID comes from. 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`](/docs/api/entities/generic) 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. | ```bash theme={"dark"} 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: ```json theme={"dark"} { "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. ```bash theme={"dark"} 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. | ```bash theme={"dark"} 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](/docs/api/entities/receipt) and the [event stream](/docs/api/entities/ledger-event) | ## 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.