Decision

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 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:

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:

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` response `data.taskId`
`initiative_id`	`POST /api/v1/initiatives` 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.

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/decisions`

`shape_context` is required in practice

Read — `GET /api/v1/decisions`

Lifecycle

All operations on this resource

Where the IDs come from

MCP equivalents

​Create — POST /api/v1/decisions

​shape_context is required in practice

​Read — GET /api/v1/decisions

​Lifecycle

​All operations on this resource

​Where the IDs come from

​MCP equivalents

Create — `POST /api/v1/decisions`

`shape_context` is required in practice

Read — `GET /api/v1/decisions`

Lifecycle

All operations on this resource

Where the IDs come from

MCP equivalents