Ask a human to look at a decision

Raise or refresh attention on a pending decision and receive a poll handle. Use it when work is blocked and a person needs to rule: carry the option you would pick, why, and what it costs to wait.

This operation writes the attention request and leaves the ruling itself to a signed-in human at resolve_url. The workspace, initiative, and run the decision belongs to are read from the decision row, so the request body carries none of them; an unrecognised field is rejected rather than ignored.

Repeating the call refreshes one attention record — the original attention_id and requested_at are kept and request_count advances — so a retry after a timeout is safe.

POST /decisions/{id}/attention

Ask a human to look at a decision

cURL

curl --request POST \
  --url https://useorgx.com/api/v1/decisions/{id}/attention \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recommended_option_id": "ship",
  "recommendation_note": "Both are reversible; shipping is the cheaper mistake.",
  "impact_if_delayed": "The rewrite blocks the launch checklist.",
  "continuation": {
    "strategy": "resume_session"
  }
}
'

202

{
  "data": {
    "decision_id": "8cf6f6a4-9a3f-4a52-8d0e-6a4c2b1f9e37",
    "status": "pending",
    "attention_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "blocking": {
      "run_id": "9c7b1d68-2c5c-4d6b-9a8e-5c4f2c0c5b4d",
      "initiative_id": "4b014796-2f1e-4a1d-9c3b-7e5a2d6f8c10",
      "workstream_id": "1f2e3d4c-5b6a-4798-8a9b-0c1d2e3f4a5b"
    },
    "poll_url": "/api/v1/decisions/8cf6f6a4-9a3f-4a52-8d0e-6a4c2b1f9e37",
    "resolve_url": "https://useorgx.com/decisions/8cf6f6a4-9a3f-4a52-8d0e-6a4c2b1f9e37",
    "poll_after_ms": 5000
  },
  "meta": {
    "apiVersion": "1",
    "workspaceId": "5be1076d-8fd0-4c0f-847f-fd67fdb935e8",
    "duplicate": false
  }
}

Authorizations

bearerAuthcookieAuth

Authorization · string · header · required

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

Headers

Idempotency-Key · string

Accepted for forward compatibility. Replay safety for this operation comes from its own state checks, described on the operation.

Required string length: 1 - 200

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

Path Parameters

id · string<uuid> · required

Decision id, as returned by POST /decisions.

Body

application/json

Every field is optional; an empty body refreshes attention with no recommendation. The schema is closed, so workspace_id, initiative_id, and run_id are rejected — those are read from the decision row instead.

recommended_option_id · string | null

An id from shape_context.options[].id on the decision.

Required string length: 1 - 120

recommendation_note · string | null

Why that option, in the words a human will read first.

Maximum string length: 2000

impact_if_delayed · string | null

What waiting costs, so a human can rank this against everything else.

Maximum string length: 500

continuation · object

Show child attributes

Response

202

application/json

Attention recorded; poll the decision for the ruling

data · object · required

Show child attributes

meta · object · required

Show child attributes