> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reconcile a Business Transaction whose outcome is pending

> For a Business Transaction left in `EXECUTING`, writes its terminal status from the execution intent: `EXECUTED` when the release is recorded, or `FAILED` when an operator recorded that nothing was released.



## OpenAPI

````yaml openapi.bundled.yaml POST /transactions/{businessTransactionId}/reconcile
openapi: 3.1.0
info:
  title: Parmana API
  version: 1.0.0
  description: >
    Parmana sits between an AI agent and the systems it acts on. An agent sends
    a Business Transaction: who

    authorized it, what action it wants, and the facts that justify it. Parmana
    evaluates the policy bound to

    the action, checks any signed human approval the policy requires, releases
    the action to the connector

    only if the policy approves, and returns a signed Execution Trust Record
    anyone can verify.


    **Authentication.** Send `Authorization: Bearer <key>` on every request. The
    only routes that need no key

    are the probes, the documents and the independent verification routes: `GET
    /health`, `GET /ready`,

    `GET /openapi.yaml`, `GET /openapi.json`, `GET /api-manifest.json`, `GET
    /documentation`,

    `GET /reference`, `GET /parmana-handbook.pdf`, `GET
    /handbook/download-leads`,

    `POST /handbook/download-leads`, `POST /refusal/verify`, `POST
    /execution-intents/verify`,

    `POST /audit/verify`, `GET /keys/{keyId}` and `GET /.well-known/jwks.json`.
    A missing or unknown key

    returns `401` before anything else runs. The server holds only a hash of
    each key. See

    [Authentication](/api-reference/authentication).


    **Two kinds of key.** An agent or service key may invoke only the
    capabilities listed on it. A human key

    (`credentialHolderType: USER`) is required for governance: proposing and
    approving policies, approvers

    and external connectors, and repairing Execution Intents. Approving or
    rejecting a change also needs a

    step up authorization signed with the checker's own step up key, and the
    checker must not be the

    person who proposed it.


    **Ownership.** Every lookup by `businessTransactionId` is scoped to the key
    that submitted the

    transaction. A transaction submitted by another key returns the same `404`
    as one that does not exist.


    **Try it live.** The "Try it" panels call production,
    `https://parmana-api-real.vercel.app`, with whatever key

    you enter. There is no public sandbox yet, so do not send test data through
    these panels.


    **Start here:** the [Quickstart](/quickstart), then [Integrate
    Parmana](/agents/integrate) for agents

    and [Connect any external system](/guides/connect-any-external-system) for
    your own endpoint.
  contact:
    name: Parmana Systems
    email: founder@parmanasystems.com
  license:
    name: Apache License 2.0, see LICENSE
    url: https://docs.parmanasystems.com/license
servers:
  - url: https://parmana-api-real.vercel.app
    description: Production. Needs a key issued by the operator.
  - url: http://localhost:3000
    description: Local (packages/api, PORT env var, default 3000)
security:
  - bearerAuth: []
tags:
  - name: Execution
    description: >-
      Executes a Business Transaction through the complete Execution Trust
      pipeline
  - name: Transactions
    description: Business Transaction creation and retrieval
  - name: Verification
    description: Deterministic verification of an Execution Trust Record
  - name: Receipts
    description: Cryptographically signed Execution Trust Receipts
  - name: Trust Records
    description: Execution Trust Record retrieval
  - name: Replay
    description: Deterministic replay of a recorded Execution Trust Record
  - name: Policies
    description: Policy existence/readability check
  - name: Policy Governance
    description: Maker-checker proposal, listing, approval, and rejection of policy changes
  - name: Approvers
    description: Maker-checker for the keys trusted to sign approvals, without a deploy
  - name: External Connectors
    description: >-
      Maker-checker for binding a capability to an operator's HTTPS endpoint and
      its policy, without a deploy (ADR-0013)
  - name: Business Signal Sources
    description: >-
      Maker-checker for the business systems Parmana asks for the facts a policy
      needs, without a deploy (RFC-0023)
  - name: Authority Grants
    description: >-
      Maker-checker for which agent may have which action decided, within which
      limits, until when (RFC-0023)
  - name: Sandbox
    description: Routes that exist only in sandbox mode, not on production
  - name: Kill Switch
    description: >-
      Operator kill switch (ADR-0017). Trip and reset need the operator
      capabilities, and probe results need the probe capability; status is open
      to any authenticated caller
  - name: Refusal Records
    description: >-
      Durable, signed evidence that a policy decision rejected a transaction
      (RFC-0021)
  - name: Execution Intents
    description: >-
      A signed statement, stored before an action is released, of exactly what
      is about to be released, plus the operator tools to find and repair a
      released action that has no signed Trust Record (ADR-0012)
  - name: Audit
    description: >-
      Signed caller-authentication audit events, independently
      third-party-verifiable
  - name: System
    description: Operational endpoints
paths:
  /transactions/{businessTransactionId}/reconcile:
    post:
      tags:
        - Transactions
      summary: Reconcile a Business Transaction whose outcome is pending
      description: >
        For a Business Transaction left in `EXECUTING`, writes its terminal
        status from the execution

        intent: `EXECUTED` when the release is recorded, or `FAILED` when an
        operator recorded that nothing

        was released. When the outcome cannot be established, nothing is changed
        and the call returns `409`

        with the reason `outcome unknown`. A transaction that is already
        terminal is not changed.

        Reconciliation never releases anything. Only human operator credentials
        may call it (`403` otherwise).
      operationId: reconcileTransaction
      parameters:
        - name: businessTransactionId
          in: path
          required: true
          description: The businessTransactionId the transaction was declared with.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: >-
            The outcome of the reconciliation. changed is false when the
            transaction was already terminal.
          content:
            application/json:
              schema:
                type: object
                properties:
                  businessTransactionId:
                    type: string
                  changed:
                    type: boolean
                  status:
                    type: string
              example:
                businessTransactionId: 9b2c4f1e-3d7a-4e8b-9f10-2a6c5d7e8f90
                changed: true
                status: EXECUTED
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: The credential is not a human operator credential.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: >-
                  Reconciliation is available only to human operator
                  credentials.
                code: NON_HUMAN_CALLER_DENIED
        '404':
          description: No Business Transaction with this id exists.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: Business Transaction not found.
                code: NOT_FOUND
        '409':
          description: >-
            The outcome is unknown: the release is not confirmed, so no
            automatic action was taken.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: >-
                  Business Transaction 'x': outcome unknown: the release is not
                  confirmed; no automatic action was taken
                code: INVALID_STATUS_TRANSITION
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            # Reconciles a transaction whose outcome is pending (status
            EXECUTING). Operator

            # credentials only: a plain API key is refused with 403. Nothing is
            released.

            TXN_ID="6f6582a1-4e1a-4800-a73b-cb4c3aa32110"

            curl -X POST
            "https://parmana-api-real.vercel.app/transactions/$TXN_ID/reconcile"
            \
              --silent \
              -H "Authorization: Bearer $PARMANA_OPERATOR_KEY"
        - lang: typescript
          label: TypeScript
          source: |-
            import { ParmanaClient } from "@parmana/sdk";

            // Operator credentials only: a plain API key is refused with 403.
            const client = new ParmanaClient({
              endpoint: "https://parmana-api-real.vercel.app",
              apiKey: process.env.PARMANA_OPERATOR_KEY!,
            });

            const result = await client.reconcileTransaction(
              "6f6582a1-4e1a-4800-a73b-cb4c3aa32110",
            );

            console.log(result.status, result.changed);
        - lang: python
          label: Python
          source: >-
            import os


            from parmana import ParmanaClient


            # Operator credentials only: a plain API key is refused with 403.

            client = ParmanaClient(
                endpoint="https://parmana-api-real.vercel.app",
                api_key=os.environ["PARMANA_OPERATOR_KEY"],
            )


            result =
            client.reconcile_transaction("6f6582a1-4e1a-4800-a73b-cb4c3aa32110")


            print(result.status, result.changed)
components:
  responses:
    Unauthorized:
      description: >-
        The `Authorization` header is missing, is not a bearer key, or names a
        key the server does not know. Nothing ran. Send a valid key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.schema'
          examples:
            authRequired:
              summary: Real captured response, missing or invalid Authorization header
              value:
                error: authentication required
  schemas:
    error.schema:
      title: Error Response
      description: >-
        Shared error envelope produced by
        packages/api/src/middleware/error-handler.ts and by every route's inline
        validation checks. error is always a plain human-readable string (never
        a nested object). code is present only when the failure was a
        RuntimeError subclass reaching the centralized error handler
        (VerificationFailedError, ReceiptGenerationError, or an uncategorized
        RuntimeError); it is absent from every inline route-level check
        (businessTransactionId format/required checks) and from
        BusinessTransactionValidationError, PolicyValidationError,
        SignalValidationError, PolicyNotFoundError,
        DuplicateBusinessTransactionError, and the generic 500 fallback. POST
        /policies/validate does NOT use this envelope at all. See its own
        response schema. For the triggering condition and recommended caller
        action behind any specific error/code/status combination, see the Error
        catalog at /api-reference/error-catalog.
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: >-
            Stable machine-readable error code. Only present for errors that
            reach the handler as a RuntimeError.
          examples:
            - RUNTIME_ERROR
            - VERIFICATION_FAILED
            - RECEIPT_GENERATION_FAILED
            - POLICY_DENIED
            - CAPABILITY_NOT_ALLOWED
            - RATE_LIMITED
            - AUDIT_UNAVAILABLE
            - SIGNING_UNAVAILABLE
            - CONNECTOR_NOT_REGISTERED
            - EXECUTION_RECORD_INCOMPLETE
            - EXECUTION_INTENT_UNAVAILABLE
            - EXECUTION_INTENT_RESULT_NOT_RECORDED
            - EXECUTION_INTENT_NOT_FOUND
            - EXECUTION_INTENTS_NOT_ENABLED
            - EXECUTION_INTENT_NOT_RESOLVABLE
            - EXECUTION_INTENT_RESOLUTION_INVALID
            - NON_HUMAN_CALLER_DENIED
            - EXECUTION_OUTCOME_UNKNOWN
            - AUTHORIZATION_NO_LONGER_VALID
        executionStatus:
          type: string
          enum:
            - EXECUTION_UNKNOWN
            - NOT_EXECUTED
          description: >-
            RFC-0023 phase 4. EXECUTION_UNKNOWN with EXECUTION_OUTCOME_UNKNOWN:
            the action was released and the call failed, so whether it ran is
            unknown; never reported as failed, and the Execution Intent stays
            ERRORED until a person resolves it. NOT_EXECUTED with
            AUTHORIZATION_NO_LONGER_VALID: the release was refused because a
            business condition or the authority grant it rested on no longer
            held, and nothing was sent.
      examples:
        - error: businessTransactionId must be a valid UUID.
        - error: >-
            Business Transaction 'eed2a972-1bf5-4166-8472-761f76fbf1b2' already
            exists.
        - error: >-
            Execution rejected: Vendor payment rejected because the assessed
            payment risk exceeds the maximum permitted threshold.
          code: RUNTIME_ERROR
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Caller API key issued by scripts/generate-api-key.ts. Sent as
        Authorization: Bearer <key>. Verified against a stored SHA-256 hash in
        constant time by packages/api/src/auth/StaticKeyAuthenticator.ts.
        Required on every route not listed as exempt in this document's
        top-level description. See /api-reference/authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.