> ## 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.

# Rule on a decision

> Record a human ruling: `approved`, `adjusted` (approved with modifications captured in
`resolution_context`), or `archived` (superseded or no longer relevant).

Authentication is a signed-in browser session with a CSRF token, and that is enforced by
which middleware this route composes rather than by a check inside the handler — an
`oxk_` API key or a service credential reaches a 401 at the session gate. A delegated
credential is weaker evidence than a person's own action, so agents raise attention with
`POST /decisions/{id}/attention` and wait for the ruling here.



## OpenAPI

````yaml /openapi/v1.yaml post /decisions/{id}/resolution
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}/resolution:
    post:
      tags:
        - Decisions
      summary: Rule on a decision
      description: >-
        Record a human ruling: `approved`, `adjusted` (approved with
        modifications captured in

        `resolution_context`), or `archived` (superseded or no longer relevant).


        Authentication is a signed-in browser session with a CSRF token, and
        that is enforced by

        which middleware this route composes rather than by a check inside the
        handler — an

        `oxk_` API key or a service credential reaches a 401 at the session
        gate. A delegated

        credential is weaker evidence than a person's own action, so agents
        raise attention with

        `POST /decisions/{id}/attention` and wait for the ruling here.
      operationId: resolveDecision
      parameters:
        - $ref: '#/components/parameters/DecisionId'
        - $ref: '#/components/parameters/IdempotencyKeyOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionResolutionRequest'
            example:
              resolution: approved
              selected_option_id: ship
              note: Cheaper and reversible; revisit after the launch.
      responses:
        '200':
          description: The decision after the ruling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionDetailResponse'
              example:
                data:
                  id: 8cf6f6a4-9a3f-4a52-8d0e-6a4c2b1f9e37
                  workspace_id: 5be1076d-8fd0-4c0f-847f-fd67fdb935e8
                  title: Approve the pricing page rewrite
                  shape: option_select
                  urgency: urgent
                  status: approved
                  resolution: approved
                  resolution_context:
                    selected_option_id: ship
                  resolved_at: '2026-08-19T15:20:00.000Z'
                  is_resolved: true
                  blocks_task: true
                  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
                  created_at: '2026-08-19T15:04:00.000Z'
                  updated_at: '2026-08-19T15:20:00.000Z'
                meta:
                  apiVersion: '1'
                  workspaceId: 5be1076d-8fd0-4c0f-847f-fd67fdb935e8
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The session is missing a valid CSRF token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - 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:
    DecisionResolutionRequest:
      type: object
      additionalProperties: false
      required:
        - resolution
      properties:
        resolution:
          type: string
          enum:
            - approved
            - adjusted
            - archived
        resolution_context:
          type: object
          additionalProperties: true
          description: >-
            Structured record of what was decided, for `adjusted` rulings
            especially.
        note:
          type: string
          maxLength: 4000
          description: Human note kept with the decision's audit trail.
        selected_option_id:
          type: string
          minLength: 1
          maxLength: 120
          description: >-
            For `option_select` decisions, the chosen
            `shape_context.options[].id`.
        selected_option_ids:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 120
          description: For `option_multiselect` decisions, the chosen option ids.
    DecisionDetailResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/DecisionDetail'
        meta:
          type: object
          properties:
            apiVersion:
              type: string
            workspaceId:
              type: string
              format: uuid
    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
    DecisionDetail:
      type: object
      additionalProperties: false
      required:
        - id
        - workspace_id
        - status
        - poll_url
        - resolve_url
      properties:
        id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
          nullable: true
        title:
          type: string
          nullable: true
        summary:
          type: string
          nullable: true
        decision_type:
          type: string
          nullable: true
        shape:
          type: string
          enum:
            - generic
            - artifact_review
            - icp_confirm
            - budget_approval
            - handoff_route
            - plan_adjust
            - task_restart
            - escalation
            - option_select
            - option_multiselect
        shape_context:
          type: object
          additionalProperties: true
        urgency:
          type: string
          nullable: true
          enum:
            - deferred
            - standard
            - urgent
            - critical
            - null
        priority:
          type: string
          nullable: true
          enum:
            - low
            - medium
            - high
            - urgent
            - null
        status:
          type: string
          nullable: true
          enum:
            - pending
            - approved
            - declined
            - rejected
            - superseded
            - cancelled
            - null
        resolution:
          type: string
          nullable: true
          enum:
            - approved
            - adjusted
            - archived
            - null
        resolution_context:
          type: object
          additionalProperties: true
        resolution_summary:
          type: string
          nullable: true
        resolved_at:
          type: string
          nullable: true
        is_resolved:
          type: boolean
          description: >-
            Whether a human has ruled. The identity of the resolver stays
            server-side.
        blocks_task:
          type: boolean
        blocking:
          $ref: '#/components/schemas/DecisionBlockingScope'
        attention:
          $ref: '#/components/schemas/DecisionAttentionState'
        poll_url:
          type: string
          description: Re-read this decision here.
        resolve_url:
          type: string
          description: Where a signed-in human rules on it.
        due_at:
          type: string
          nullable: true
        created_at:
          type: string
          nullable: true
        updated_at:
          type: string
          nullable: true
    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
    DecisionAttentionState:
      type: object
      nullable: true
      description: >-
        The standing request for a human to look at this decision. Continuation
        routing material

        held alongside it — peer and session handles — stays server-side; the
        fields here are the

        ones a caller needs in order to judge whether to act.
      properties:
        protocol:
          type: string
          nullable: true
          enum:
            - orgx.attention.v1
            - null
        kind:
          type: string
          nullable: true
          enum:
            - question
            - permission
            - approval
            - recovery
            - null
        blocking:
          type: boolean
        response_mode:
          type: string
          nullable: true
        impact_if_delayed:
          type: string
          nullable: true
        recommendation_note:
          type: string
          nullable: true
        recommended_option_id:
          type: string
          nullable: true
        recommended_action:
          type: string
          nullable: true
        attention_id:
          type: string
          nullable: true
        requested_at:
          type: string
          nullable: true
          description: When attention was first raised. Stable across refreshes.
        refreshed_at:
          type: string
          nullable: true
        request_count:
          type: integer
          description: How many times attention has been raised or refreshed.
        continuation:
          type: object
          properties:
            strategy:
              type: string
              nullable: true
              enum:
                - reply_in_place
                - resume_session
                - followup_from_checkpoint
                - poll
                - none
                - null
            state:
              type: string
              nullable: true
              enum:
                - waiting
                - answer_received
                - resuming
                - resumed
                - resume_failed
                - cancelled
                - null
  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'
    Conflict:
      description: Idempotency or expected-version conflict
      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:
    cookieAuth:
      type: apiKey
      in: cookie
      name: __session
      description: Session cookie from web authentication

````