Raise a decision

Create a decision request for a human ruling. Automated callers raise and read decisions; approving or declining stays a signed-in human action, recorded with lifecycle history.

Reuse the same Idempotency-Key and request body to receive the original decision. Reusing the key with a different body returns an idempotency conflict.

POST /decisions

Raise a decision

cURL

curl --request POST \
  --url https://useorgx.com/api/v1/decisions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "workspace_id": "5be1076d-8fd0-4c0f-847f-fd67fdb935e8",
  "title": "Approve the pricing page rewrite"
}
'

200

{
  "decision": {
    "id": "8cf6f6a4-9a3f-4a52-8d0e-6a4c2b1f9e37",
    "workspace_id": "5be1076d-8fd0-4c0f-847f-fd67fdb935e8",
    "title": "Approve the pricing page rewrite",
    "status": "pending",
    "shape": "option_select",
    "urgency": "urgent",
    "blocks_task": false,
    "created_at": "2026-08-19T15:04:00.000Z",
    "updated_at": "2026-08-19T15:04:00.000Z"
  }
}

Authorizations

bearerAuthcookieAuth

Authorization · string · header · required

OrgX API key, sent as Authorization: Bearer oxk_...

Headers

Idempotency-Key · string · required

Workspace-scoped retry key for safe mutation replay.

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$

Body

application/json

workspace_id · string<uuid> · required

title · string · required

Required string length: 1 - 500

description · string

Maximum string length: 8000

shape · enum<string> · default: generic

Available options: generic, artifact_review, icp_confirm, budget_approval, handoff_route, plan_adjust, task_restart, escalation, option_select, option_multiselect

shape_context · object

urgency · enum<string> · default: standard

Available options: deferred, standard, urgent, critical

blocks_task · boolean

task_id · string<uuid>

initiative_id · string<uuid>

Response

200

application/json

The original decision returned for an idempotent replay

decision · object · required

A decision request awaiting or carrying a human ruling. Additional lifecycle fields (resolution, priority, due dates, occurrence tracking) appear as the decision progresses.

Show child attributes