> ## 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. # Decision > The decision resource: raise decisions over REST, read their state, and understand why resolution is deliberately human-only. A decision is a durable request for a human ruling: an agent or integration raises it, a person approves or declines it, and the resolution is recorded with lifecycle history. The REST surface deliberately splits authority: **any API key can raise and read decisions; only a signed-in human can resolve one.** Endpoints that would let an automated caller assert a human ruling return `403 direct_human_decision_action_required`. The dedicated `/api/v1/decisions` resource is canonical. The older `decision` record on [`/api/entities`](/docs/api/entities/generic) remains a compatibility read and write for older clients. ## Create — `POST /api/v1/decisions` Accepts `Authorization: Bearer oxk_...` or a web-app session. Every create requires an `Idempotency-Key`. Reuse the same key and body to get the original decision with `200`; reuse it with a different body returns `409 idempotency_key_conflict`. | Field | Type | Required | Meaning | | --------------- | ----------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `workspace_id` | UUID | yes | Target workspace. | | `title` | string, 1–500 | yes | What needs deciding. | | `description` | string ≤8000 | no | Context for the decider. | | `shape` | enum | no | `generic` (default), `artifact_review`, `icp_confirm`, `budget_approval`, `handoff_route`, `plan_adjust`, `task_restart`, `escalation`, `option_select`, `option_multiselect`. | | `shape_context` | JSON object | **yes in practice** | Validated against the declared shape. Defaults to `{}`, and `{}` fails every shape — see the table below. | | `urgency` | `deferred` `standard` `urgent` `critical` | no | Defaults to `standard`. | | `blocks_task` | boolean | no | Whether the referenced task is blocked until this resolves. | | `task_id` | UUID | no | The blocked or related task. | | `initiative_id` | UUID | no | Scope linkage. | ### `shape_context` is required in practice `shape` defaults to `generic` and `shape_context` defaults to `{}`, but `{}` satisfies no shape. A body of only `workspace_id` and `title` therefore fails with `400 invalid_shape_context`. Send the context its shape requires: | `shape` | Required in `shape_context` | | -------------------- | ---------------------------------------------------------------------------------------- | | `generic` (default) | `description` (non-empty string) | | `artifact_review` | `artifact_id`, `artifact_title` | | `icp_confirm` | `persona`, `criteria` (≥1 string) | | `budget_approval` | `amount_usd_cents` (positive integer), `purpose` | | `handoff_route` | `from_agent`, `candidate_agents` (≥1 agent slug), `open_questions` (array, may be empty) | | `plan_adjust` | `reason`, `proposed_changes` | | `task_restart` | `task_id`, `failure_reason` | | `escalation` | `trigger`, `recommended_action` | | `option_select` | `question`, `options` (**2–6** items, each `{ id, label }`) | | `option_multiselect` | `question`, `options` (**3–12** items, each `{ id, label }`) | Every shape also accepts an optional `estimate`. Note the distinction: the top-level `description` field is optional and is stored as the decision summary; `shape_context.description` is the required body of a `generic` decision. The smallest request that succeeds: ```bash theme={"dark"} curl https://useorgx.com/api/v1/decisions \ -X POST \ -H "Authorization: Bearer $ORGX_API_KEY" \ -H 'Idempotency-Key: pricing-page-decision-001' \ -H 'Content-Type: application/json' \ -d '{ "workspace_id": "3d7e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a", "title": "Approve the pricing page rewrite", "shape_context": { "description": "The rewrite is staged and needs a go/no-go." } }' ``` An option decision, with the two-option minimum: ```bash theme={"dark"} curl https://useorgx.com/api/v1/decisions \ -X POST \ -H "Authorization: Bearer $ORGX_API_KEY" \ -H 'Idempotency-Key: pricing-page-option-001' \ -H 'Content-Type: application/json' \ -d '{ "workspace_id": "3d7e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a", "title": "Approve the pricing page rewrite", "shape": "option_select", "urgency": "urgent", "shape_context": { "question": "Ship the rewrite now or take one more pass?", "options": [ { "id": "ship", "label": "Ship it" }, { "id": "revise", "label": "One more pass" } ] } }' ``` Returns `201` with `{ "decision": { ... } }` — keep `decision.id`. An idempotent replay returns the same shape with `200`. This endpoint returns a bare named object, not the `{ data, meta }` envelope. ## Read — `GET /api/v1/decisions` Query parameters: `workspace_id` (required), `shape`, `urgency`, `status`, `limit` (default 50, max 200). Returns `{ "decisions": [ ... ] }`. The compatibility read `GET /api/entities?type=decision` remains available for older clients and supports its generic filters (`status`, `initiative_id`, `search`, `ids`). ## Lifecycle `status` values: `pending`, `approved`, `declined`, `superseded`, `cancelled`. The write aliases `accepted` → `approved` and `rejected` → `declined` are normalized. All transitions start from `pending`. **Resolution is human-only by design.** The paths that record a ruling — `PATCH /api/v1/decisions/{id}` (resolutions `approved`, `adjusted`, `archived`, with option selection for option shapes) and the decision lifecycle actions — reject `oxk_` credentials with `403`. A person resolves decisions in Mission Control, or through an MCP client where `orgx_decide` runs under their authenticated session. Editing an existing decision is narrower still: proposal-field updates are available through the MCP `orgx_write` path while the decision is `pending`. A personal `oxk_` key receives `403` even for proposal fields. Only proposal fields (`title`, `summary`, `description`, `priority`, `due_at`, `recommended_action`, `blocks_task`, `estimate`, `urgency`, `urgency_score`) are editable, and only while the decision is still `pending` (`409` otherwise). With an API key, get the decision right at creation time. ## All operations on this resource | Operation | Method + path | Auth | Notes | | -------------------------- | ----------------------------------------------------------- | --------------- | ------------------------------------------------------------------------ | | Create | `POST /api/v1/decisions` | API key/session | Shape-validated. `Idempotency-Key` required; returns `{ decision }`. | | Create (compatibility) | `POST /api/entities` with `type: "decision"` | API key | Older clients only; status is forced to `pending`. | | List | `GET /api/v1/decisions?workspace_id=...` | API key/session | Filters: `shape`, `urgency`, `status`, `limit`. | | List / get (compatibility) | `GET /api/entities?type=decision` | API key | Older clients only; use the v1 list/detail operations for new work. | | Edit proposal | Compatibility `PATCH /api/entities` with `type: "decision"` | MCP only | Pending decisions, proposal fields; API keys receive `403`. | | Resolve | `PATCH /api/v1/decisions/{id}` | Session only | Human ruling: `approved`, `adjusted`, `archived`; option selection. | | Delete | Not exposed | — | `cancelled` and `superseded` are the terminal states, set at resolution. | ## Where the IDs come from | Field | Obtain it from | | --------------- | ------------------------------------------------------------------------------------- | | decision `id` | `POST /api/v1/decisions` response `decision.id`, or `GET /api/v1/decisions` list rows | | `workspace_id` | `GET /api/v1/me` → `data.default_workspace_id` or `data.workspaces[].id` | | `task_id` | [`POST /work`](/docs/api/entities/work-item) response `data.taskId` | | `initiative_id` | [`POST /api/v1/initiatives`](/docs/api/entities/initiative) response `data.initiativeId` | | option `id`s | You define them in `shape_context.options[].id` at creation | ## MCP equivalents `orgx_decide` covers the full loop: `create` and list use the decision resource; `approve` and `reject` run under the signed-in user's authority. `orgx_search` with `type=decision` reads the same records this page describes.