Ask a human to look at a decision

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"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://useorgx.com/api/v1/decisions/{id}/attention', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://useorgx.com/api/v1/decisions/{id}/attention"

payload = {
    "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" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

Decisions

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 --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"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
  })
};

fetch('https://useorgx.com/api/v1/decisions/{id}/attention', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://useorgx.com/api/v1/decisions/{id}/attention"

payload = {
    "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" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {},
    "requestId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "docsUrl": "<string>",
    "retryAfter": 123
  }
}

Authorizations

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

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

Attention recorded; poll the decision for the ruling

data

object

required

Show child attributes

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

Ask a human to look at a decision

Authorizations

Headers

Path Parameters

Body

Response