> ## 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.

<Note>
  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.
</Note>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.