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

# Reconcile one domain controller in shadow mode

> Produces a typed shadow proposal candidate or no-op. A proposal is atomically admitted as a pending human Decision with canonical decision.proposed evidence and a neutral reconciliation Receipt. It grants no execution or policy authority.



## OpenAPI

````yaml /openapi/v1.yaml post /controllers/{domain}/reconcile
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: Controllers
    description: Shadow-only domain controller status and reconciliation
  - 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:
  /controllers/{domain}/reconcile:
    parameters:
      - name: domain
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/ControllerDomain'
    post:
      tags:
        - Controllers
      summary: Reconcile one domain controller in shadow mode
      description: >-
        Produces a typed shadow proposal candidate or no-op. A proposal is
        atomically admitted as a pending human Decision with canonical
        decision.proposed evidence and a neutral reconciliation Receipt. It
        grants no execution or policy authority.
      operationId: reconcileController
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControllerReconcileRequest'
            example:
              workspace_id: 11111111-1111-4111-8111-111111111111
              idempotency_key: growth-cadence-canary-2026-08-26
              mode: shadow
              protocol_version: orgx.controller.v1
              spec_revision: >-
                controller_spec_revision:09a53f2c0987b63cf07557d50b378e8ad2473591a943ceb6f6912e0e7c679015
              input_cursor: >-
                sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd
              max_input_age_seconds: 86400
      responses:
        '200':
          description: Persisted terminal reconcile result or exact replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControllerResponse'
              example:
                data:
                  controller_id: domain.growth
                  domain: growth
                  spec_revision: >-
                    controller_spec_revision:09a53f2c0987b63cf07557d50b378e8ad2473591a943ceb6f6912e0e7c679015
                  run_id: >-
                    controller_run:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
                  last_run_id: >-
                    controller_run:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
                  status: degraded
                  result: noop
                  last_result: noop
                  last_signal_id: null
                  last_signal_state: null
                  last_error_code: null
                  event_ids:
                    - 33333333-3333-4333-8333-333333333333
                    - 44444444-4444-4444-8444-444444444444
                  projection_cursor: '2'
                  decision_id: null
                  decision_event_id: null
                  receipt_id: null
                  last_receipt_id: null
                  duplicate: false
                  protocol_version: orgx.controller.v1
                  mode: shadow
                  proposal: null
                  learning_proposal: null
                  noop_reason: insufficient_evidence
                  source_health:
                    state: insufficient_evidence
                    observedAt: '2026-08-26T08:10:00.000Z'
                    freshnessWatermark: null
                    sourceCursor: null
                    recordCount: 0
                    limitations:
                      - No completed work met the active evidence profile.
                  limitations:
                    - >-
                      Shadow proposals require human review and have no
                      authority effect.
                    - >-
                      Receipt fields remain null until canonical execution
                      admission exists.
                meta:
                  apiVersion: '1'
                  workspaceId: 11111111-1111-4111-8111-111111111111
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerAuth: []
        - cookieAuth: []
components:
  schemas:
    ControllerDomain:
      type: string
      enum:
        - product
        - engineering
        - growth
        - sales
        - design
        - operations
    ControllerReconcileRequest:
      type: object
      additionalProperties: false
      required:
        - workspace_id
        - idempotency_key
        - mode
        - protocol_version
      properties:
        workspace_id:
          type: string
          format: uuid
        idempotency_key:
          type: string
          minLength: 1
          maxLength: 200
        mode:
          type: string
          const: shadow
        protocol_version:
          type: string
          const: orgx.controller.v1
        spec_revision:
          type: string
          pattern: ^controller_spec_revision:[a-f0-9]{64}$
        input_cursor:
          type: string
          minLength: 1
          maxLength: 512
        max_input_age_seconds:
          type: integer
          minimum: 1
          maximum: 604800
    ControllerResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/ControllerApiResult'
        meta:
          type: object
          required:
            - apiVersion
            - workspaceId
          properties:
            apiVersion:
              type: string
              const: '1'
            workspaceId:
              type: string
              format: uuid
    ControllerApiResult:
      type: object
      additionalProperties: false
      required:
        - controller_id
        - domain
        - spec_revision
        - run_id
        - last_run_id
        - status
        - result
        - last_result
        - last_signal_id
        - last_signal_state
        - last_error_code
        - event_ids
        - projection_cursor
        - decision_id
        - decision_event_id
        - receipt_id
        - last_receipt_id
        - duplicate
        - protocol_version
        - mode
        - proposal
        - learning_proposal
        - noop_reason
        - source_health
        - limitations
      properties:
        controller_id:
          type: string
          pattern: ^domain\.[a-z][a-z0-9_-]{1,63}$
        domain:
          $ref: '#/components/schemas/ControllerDomain'
        spec_revision:
          type: string
          pattern: ^controller_spec_revision:[a-f0-9]{64}$
        run_id:
          type:
            - string
            - 'null'
          pattern: ^controller_run:[a-f0-9]{64}$
        last_run_id:
          type:
            - string
            - 'null'
          pattern: ^controller_run:[a-f0-9]{64}$
        status:
          type: string
          enum:
            - never_run
            - running
            - healthy
            - degraded
            - failed
        result:
          type: string
          description: >-
            On a never_run status read, noop is a transport sentinel; null run
            IDs and last_result distinguish absence from a completed no-op.
          enum:
            - proposal
            - noop
        last_result:
          type:
            - string
            - 'null'
          enum:
            - proposal
            - noop
            - null
        last_signal_id:
          type:
            - string
            - 'null'
        last_signal_state:
          type:
            - string
            - 'null'
          enum:
            - observed
            - cleared
            - null
        last_error_code:
          type:
            - string
            - 'null'
        event_ids:
          type: array
          items:
            type: string
        projection_cursor:
          type: string
        decision_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Pending canonical Decision admitted for the shadow proposal.
        decision_event_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Canonical decision.proposed event; never the Receipt identity.
        receipt_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Neutral proposal-admission reconciliation Receipt with no authority.
        last_receipt_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Receipt for the latest admitted controller proposal, when present.
        duplicate:
          type: boolean
        protocol_version:
          type: string
          const: orgx.controller.v1
        mode:
          type: string
          const: shadow
        proposal:
          type:
            - object
            - 'null'
          additionalProperties: true
        learning_proposal:
          type:
            - object
            - 'null'
          additionalProperties: true
        noop_reason:
          type:
            - string
            - 'null'
        source_health:
          type:
            - object
            - 'null'
          additionalProperties: true
        limitations:
          type: array
          items:
            type: string
    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
  parameters:
    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.
  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:
    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

````