> ## 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. # 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. ## OpenAPI ````yaml /openapi/v1.yaml post /decisions/{id}/attention openapi: 3.1.0 info: title: OrgX REST API v1 version: '1' description: >- Build accountable work into your product with OrgX REST API v1. Create work with one field, attach evidence when it is complete, and keep the receipt. Every authenticated request is scoped to the workspace resolved from your credential. Start with `POST /work`. Human guide: https://docs.useorgx.com/docs/api/quickstart contact: name: OrgX Support url: https://useorgx.com/support email: support@useorgx.com license: name: Proprietary url: https://useorgx.com/terms servers: - url: https://useorgx.com/api/v1 description: Production security: [] tags: - name: Work description: Create accountable work and complete it with evidence - name: Initiatives description: Organize related work around an outcome - name: Operating processes description: Evidence-backed company workflow/process lifecycle - name: Operating map description: Derived, rebuildable Operating Map projection over the process ledger - name: Discovery runs description: Wizard and deep-search workflow discovery over connected company sources - name: Handoffs description: Ledger-backed stage handoffs between operating-process stages - name: Events description: Replayable, workspace-scoped accepted ledger events - name: Projections description: Workspace-scoped, rebuildable read projections over OrgX sources - name: Episodes description: Mission-compatible Episode read adapters - name: Receipt validation description: Account-free Agent Work Receipt schema discovery and conformance - name: Receipt import description: Authenticated, workspace-scoped import into the hosted receipt ledger - name: Workload diagnosis description: >- Account-free evaluation of time, agents, systems, authority, and accountability boundaries - name: Content Studio description: >- Estimate, showcase, checkout, and payment event operations for Content Studio - name: Decisions description: Raise decisions for human ruling and read their state - name: Artifacts description: Register produced work against the entity it belongs to - name: Launches description: Preview and run an initiative launch through its spend gates - name: Runs description: Control agent runs with pause, resume, cancel, and rollback - name: Lifecycle description: Pause, resume, retry, or cancel work hierarchy nodes and runs - name: Deduplication description: Claim durable event fingerprints so duplicate triggers fire once - name: Credential description: >- Resolve the calling credential, the workspaces it reaches, and what it may do - name: API discovery description: Account-free error codes, request schemas, and closed vocabularies for v1 externalDocs: description: Human-readable OrgX REST API v1 reference url: https://docs.useorgx.com/docs/api/public-api paths: /decisions/{id}/attention: post: tags: - Decisions summary: Ask a human to look at a decision description: >- 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. operationId: raiseDecisionAttention parameters: - $ref: '#/components/parameters/DecisionId' - $ref: '#/components/parameters/IdempotencyKeyOptional' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/DecisionAttentionRequest' example: 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 responses: '202': description: Attention recorded; poll the decision for the ruling content: application/json: schema: $ref: '#/components/schemas/DecisionAttentionResponse' example: 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 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: The decision has already been resolved content: application/json: schema: $ref: '#/components/schemas/ApiError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerAuth: [] - cookieAuth: [] components: parameters: DecisionId: name: id in: path required: true schema: type: string format: uuid description: Decision id, as returned by POST /decisions. IdempotencyKeyOptional: name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$ description: >- Accepted for forward compatibility. Replay safety for this operation comes from its own state checks, described on the operation. schemas: DecisionAttentionRequest: type: object additionalProperties: false description: >- 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. properties: recommended_option_id: type: string minLength: 1 maxLength: 120 nullable: true description: An id from `shape_context.options[].id` on the decision. recommendation_note: type: string maxLength: 2000 nullable: true description: Why that option, in the words a human will read first. impact_if_delayed: type: string maxLength: 500 nullable: true description: >- What waiting costs, so a human can rank this against everything else. continuation: type: object additionalProperties: false properties: strategy: type: string default: poll enum: - reply_in_place - resume_session - followup_from_checkpoint - poll - none description: How the caller expects to be resumed once a human rules. DecisionAttentionResponse: type: object required: - data - meta properties: data: type: object required: - decision_id - poll_url - resolve_url - poll_after_ms properties: decision_id: type: string format: uuid status: type: string nullable: true attention_id: type: string nullable: true description: Stable across refreshes of the same attention request. blocking: $ref: '#/components/schemas/DecisionBlockingScope' poll_url: type: string resolve_url: type: string poll_after_ms: type: integer description: Suggested wait before re-reading the decision. meta: type: object properties: apiVersion: type: string workspaceId: type: string format: uuid duplicate: type: boolean description: >- True when this call refreshed an attention request that already existed. ApiError: type: object properties: error: type: object properties: code: type: string message: type: string details: type: object requestId: type: string timestamp: type: string format: date-time docsUrl: type: string format: uri retryAfter: type: integer description: Seconds until rate limit resets DecisionBlockingScope: type: object description: >- What the decision is holding up. Read from the decision row, never supplied by a caller. properties: run_id: type: string format: uuid nullable: true initiative_id: type: string format: uuid nullable: true workstream_id: type: string format: uuid nullable: true responses: BadRequest: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: Resource is unavailable to the caller content: application/json: schema: $ref: '#/components/schemas/ApiError' ServiceUnavailable: description: Ledger or workspace authorization is unavailable content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearerAuth: type: http scheme: bearer description: 'OrgX API key, sent as `Authorization: Bearer oxk_...`' cookieAuth: type: apiKey in: cookie name: __session description: Session cookie from web authentication ````