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

# Execute a declared Business Transaction

> Decides, signs and releases a Business Transaction that was declared with `POST /transactions`, then verifies it.



## OpenAPI

````yaml openapi.bundled.yaml POST /transactions/{businessTransactionId}/execute
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}/execute:
    post:
      tags:
        - Transactions
      summary: Execute a declared Business Transaction
      description: >
        Decides, signs and releases a Business Transaction that was declared
        with `POST /transactions`,

        then verifies it. The caller must be the one that declared it. The
        status walks

        `RECEIVED` → `POLICY_EVALUATED` → `APPROVED` (or `REJECTED`) →
        `EXECUTING` → `EXECUTED` → `VERIFIED`.

        A transaction that is not `RECEIVED` is never released again by this
        call. One that is `EXECUTING`

        is refused with `409` and the reason `outcome pending`: its outcome is
        decided by reconciliation.

        If the action was released but the status could not be set to
        `EXECUTED`, the call answers `202` with `outcome: pending`, `status:
        EXECUTING` and the signed record. Nothing is released again; reconcile
        with `POST /transactions/{businessTransactionId}/reconcile`.
      operationId: executeDeclaredTransaction
      parameters:
        - name: businessTransactionId
          in: path
          required: true
          description: The businessTransactionId the transaction was declared with.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: >-
            Released and recorded. The body is the signed Execution Trust
            Record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/execution-trust-record-response.schema'
              examples:
                test-fixture-flow:
                  summary: >-
                    Real captured response, currently runnable (pairs with the
                    test-fixture-flow request example above; APPROVED)
                  value:
                    trustRecordId: 7ec8745e-fa10-4506-a247-c5a8b794eaa5
                    businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                    transaction:
                      businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                      metadata:
                        businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                        correlationId: 9c039d73-7fb1-461f-908f-c646c905633c
                        sourceSystem: docs-api-reference
                        submittedBy: docs-example
                        submittedAt: '2026-09-14T17:17:50.000Z'
                      authority:
                        authorityId: f10f016f-b7c0-443e-8307-d26f5fa98067
                        authorityType: SERVICE
                        principalId: docs-example-caller
                        displayName: Docs Example Caller
                        issuedAt: '2026-09-14T17:17:50.000Z'
                      authorization:
                        authorizationId: 5f112f4c-a43d-41dd-bfee-66a49efe33de
                        authorityId: f10f016f-b7c0-443e-8307-d26f5fa98067
                        purpose: 'API reference example: refund authorization'
                        issuedAt: '2026-09-14T17:17:50.000Z'
                      intent:
                        intentId: 462c2efd-3b88-4f59-8c47-8ba01a63d37e
                        authorizationId: 5f112f4c-a43d-41dd-bfee-66a49efe33de
                        action: test:fixture-execute
                        target: vendor://payments
                        parameters:
                          amount: 1000
                          currency: USD
                        createdAt: '2026-09-14T17:17:50.000Z'
                      policy:
                        name: vendor-payment
                        version: 2.0.0
                        schemaVersion: 1.0.0
                        contentHash: >-
                          27b396d84540aa792d88566da38537b671195c0c0049bac3aca41d4544a12b1a
                      signals:
                        vendorVerified: true
                        invoiceVerified: true
                        paymentApproved: true
                        sufficientFunds: true
                        paymentAmount: 1000
                        riskScore: 5
                        vendorId: vendor://payments
                      status: RECEIVED
                      createdAt: '2026-09-14T17:17:55.617Z'
                    authorization:
                      payload:
                        version: 1
                        authorizationId: 381ef27a-0955-4085-9e5d-e4223fef2986
                        nonce: ed25c17c-c0b2-4600-b445-3c8cb557ac12
                        decisionId: b83deff8-ef50-49d0-830f-741cba8f5668
                        businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                        policyName: vendor-payment
                        policyVersion: 2.0.0
                        policyContentHash: >-
                          27b396d84540aa792d88566da38537b671195c0c0049bac3aca41d4544a12b1a
                        signalsHash: >-
                          50d0c4e1e3b0190c2074068627086e59049b0d2d224a71cb4fc9adf7124be287
                        submittedBy: docs-example
                        authorizedAt: '2026-09-14T17:17:55.627Z'
                        expiresAt: '2026-09-14T17:19:55.627Z'
                        businessTransactionHash: >-
                          ba5498ce2474e9ef58a9c368c70fd4cf0a497a84199218783d3b2992799a77bc
                      signature: >-
                        HZaohm/v3xrJTp+VrcJmLLcIG1SMl3LyPcHQUF6UHo7J9Z/KY92brpU92xVnPhVJJMaB+fd7nVRQ96k3OP7DBQ==
                      keyId: default
                      algorithm: ed25519
                    overrides: []
                    executions:
                      - executionId: 21a57d3e-bed5-4a73-8af9-2ac2d7e8326e
                        businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                        decision:
                          decisionId: b83deff8-ef50-49d0-830f-741cba8f5668
                          intentId: 462c2efd-3b88-4f59-8c47-8ba01a63d37e
                          policy:
                            name: vendor-payment
                            version: 2.0.0
                            schemaVersion: 1.0.0
                          signals:
                            vendorVerified: true
                            invoiceVerified: true
                            paymentApproved: true
                            sufficientFunds: true
                            paymentAmount: 1000
                            riskScore: 5
                            vendorId: vendor://payments
                          outcome: APPROVED
                          reason: >-
                            Vendor payment authorized. Vendor verification,
                            invoice verification, payment approval, funding, and
                            risk assessment requirements were satisfied.
                          evaluatedAt: '2026-09-14T17:17:55.626Z'
                        status: COMPLETED
                        mode: SYNC
                        startedAt: '2026-09-14T17:17:55.631Z'
                        metadata:
                          authorizationId: 381ef27a-0955-4085-9e5d-e4223fef2986
                        previousChainHash: null
                        chainHash: >-
                          f6f885358ddb3c820b3499d45c2a90a2624032ceece7bd53ece36809783e3220
                        chainSignature:
                          algorithm: ed25519
                          keyId: default
                          value: >-
                            uXnVWKHYHDf8xRsl9oYdfFCem3f0n6IBzm2uYmxDnEkIU8FyOKxxWxeTidnF3A0UH2XSNNIROeeRzET6X/67BQ==
                          signedAt: '2026-09-14T17:17:55.652Z'
                        evidence:
                          businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                          action: test:fixture-execute
                          target: vendor://payments
                          parameters:
                            amount: 1000
                            currency: USD
                          success: true
                          executedAt: '2026-09-14T17:17:55.646Z'
                          attributes:
                            connector:
                              connectorId: test-fixture
                              connectorVersion: 1.0.0
                              capability: test:fixture-execute
                              sanitizedEndpoint: vendor://payments
                              credentialProviderId: static
                              requestSummary:
                                businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                                action: test:fixture-execute
                                target: vendor://payments
                                parameters:
                                  amount: 1000
                                  currency: USD
                              responseSummary:
                                success: true
                                metadata: {}
                              startedAt: '2026-09-14T17:17:55.645Z'
                              completedAt: '2026-09-14T17:17:55.646Z'
                              connectorEvidenceHash: >-
                                887b000a355c96ca432c7a709b24b50e89d879bc50699bc5b5280a957d981f70
                        completedAt: '2026-09-14T17:17:55.650Z'
                    verifications:
                      - verificationId: 0e7de678-bb48-4fa0-ad53-3664d78d954b
                        businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                        status: VERIFIED
                        message: Execution Trust Record verified successfully.
                        verifiedAt: '2026-09-14T17:17:55.661Z'
                        trustRecordHash: >-
                          cd261f8b33ebd435ce31bdcafc971044aae165d12695446f587068052ce52807
                    receipts:
                      - receiptId: cf5f9ef1-1e53-459a-8f58-01c9dbe50f84
                        businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                        trustRecordHash: >-
                          cd261f8b33ebd435ce31bdcafc971044aae165d12695446f587068052ce52807
                        receiptHash: >-
                          3a028e197e0c297761fd675696a6d418ffb67a10a07954cf4ed004e4ceb9f4f0
                        issuedAt: '2026-09-14T17:17:55.662Z'
                        algorithm: ed25519
                        signature: >-
                          S0rbIGkdEIWtk1fVqcEq8I+d2xUZHZQW28SFDolnLcd3hYYAWz2YQ+LkvlQc9OzbPE0vF/75VUrvlvIcbaOTAw==
                    createdAt: '2026-09-14T17:17:55.652Z'
                    updatedAt: '2026-09-14T17:17:55.652Z'
                    trustRecordHash: >-
                      cd261f8b33ebd435ce31bdcafc971044aae165d12695446f587068052ce52807
                    signature:
                      algorithm: ed25519
                      keyId: default
                      value: >-
                        lPz+IbGAQwPuLEzB7fEgiKU3dZTEeT3aIFqC/6LIRMBGK7UZor2nVkmItNUXu9RBCziAUH3yj2EchtwX6GAXBQ==
                      signedAt: '2026-09-14T17:17:55.655Z'
        '202':
          description: >-
            Released, and the signed record was written, but the status could
            not be set to EXECUTED. The status is EXECUTING: the outcome is
            pending until an operator reconciles it.
          content:
            application/json:
              schema:
                type: object
                required:
                  - businessTransactionId
                  - status
                  - outcome
                  - reconcile
                  - record
                properties:
                  businessTransactionId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                      - EXECUTING
                  outcome:
                    type: string
                    enum:
                      - pending
                  reconcile:
                    type: string
                    description: The path to reconcile the transaction with.
                  record:
                    type: object
                    description: The signed Execution Trust Record, as in the 200 response.
              examples:
                status-write-failed:
                  summary: The release happened; the EXECUTED status write failed
                  value:
                    businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
                    status: EXECUTING
                    outcome: pending
                    reconcile: >-
                      /transactions/e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a/reconcile
                    record:
                      businessTransactionId: e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Refused, with the same codes and meaning as `POST /execute`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
              examples:
                principalNotAllowed:
                  summary: >-
                    Real captured response, principalId not permitted for this
                    caller
                  value:
                    error: >-
                      Caller is not permitted to assert this
                      authority.principalId.
                capabilityNotAllowed:
                  summary: The key may not invoke this action
                  value:
                    error: Caller is not permitted to invoke this capability.
                    code: CAPABILITY_NOT_ALLOWED
                policyDenied:
                  summary: A policy rejected the transaction, a final decision
                  value:
                    error: >-
                      Execution rejected: Vendor payment rejected because the
                      assessed payment risk exceeds the maximum permitted
                      threshold.
                    code: POLICY_DENIED
        '404':
          description: >-
            `policy.name` and `policy.version` do not match a policy this server
            has.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
              examples:
                policyNotFound:
                  summary: >-
                    Real captured response, unknown policy referenced by the
                    transaction
                  value:
                    error: Policy 'does-not-exist' version '9.9.9' was not found.
        '409':
          description: >-
            The status does not allow execution (for example VERIFIED), or the
            outcome is pending (EXECUTING, `outcome pending`). Nothing ran
            again.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  code:
                    type: string
              example:
                error: >-
                  Business Transaction '11111111-1111-4111-8111-111111111111':
                  status is EXECUTING: outcome pending
                code: INVALID_STATUS_TRANSITION
        '502':
          description: >-
            `EXECUTION_OUTCOME_UNKNOWN`: released, then the connector call
            failed. Do not resend under a new id; check the target system, then
            resolve the intent. See `POST /execute`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
              examples:
                executionOutcomeUnknown:
                  summary: The action was released and the connector call failed
                  value:
                    error: >-
                      The action for business transaction
                      '38dcf000-99ed-43af-8666-46c63c8ada74' was released to the
                      execution system, but the call failed, so whether it was
                      performed is unknown. Do not retry as a new transaction:
                      check the target system, then close the Execution Intent
                      with POST
                      /execution-intents/38dcf000-99ed-43af-8666-46c63c8ada74/resolve.
                      authorizationId: 4d291c90-9e93-4a8a-b214-8cc6526fe2e3.
                    code: EXECUTION_OUTCOME_UNKNOWN
        '503':
          $ref: '#/components/responses/SigningUnavailable'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            # Executes a declared Business Transaction. Declare it first with
            POST /transactions

            # (see the createTransaction sample), then set TXN_ID to its
            businessTransactionId.

            # Nothing is released before this call.

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

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

            import { readFileSync } from "node:fs";


            const client = new ParmanaClient({
              endpoint: "https://parmana-api-real.vercel.app",
              apiKey: process.env.PARMANA_API_KEY!,
            });


            const inEffect = await client.policyInEffect("paytm:refund");


            // The signed approval the approver sent, for this order and up to
            this amount.

            const approval = JSON.parse(readFileSync("approval.json", "utf8"));


            const transaction = createBusinessTransaction({
              principalId: (await client.caller()).callerId,
              purpose: "Refund order ORD-1042",
              action: "paytm:refund",
              target: "ORD-1042",
              parameters: { orderId: "ORD-1042", transactionId: "TXN-9", amount: 750 },
              policy: inEffect.policy,
              signals: {
                refundEligible: true,
                fraudCheckPassed: true,
                refundAmount: 750,
                managerApproved: true,
                approvalArtifact: approval,
              },
            });


            const declared = await client.declareTransaction(transaction);


            // Nothing is released until this call.

            const record = await
            client.executeTransaction(declared.businessTransactionId);


            console.log(
              record.businessTransactionId,
              record.executions[0]?.decision.outcome,
            );
        - lang: python
          label: Python
          source: >-
            import json

            import os

            from pathlib import Path


            from parmana import ParmanaClient, create_business_transaction


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


            in_effect = client.policy_in_effect("erp:invoice-pay")


            # The signed approval the approver sent, for this order and up to
            this amount.

            approval = json.loads(Path("approval.json").read_text())


            transaction = create_business_transaction(
                principal_id=client.caller().caller_id,
                purpose="Refund order ORD-1042",
                action="erp:invoice-pay",
                target="ORD-1042",
                parameters={"orderId": "ORD-1042", "transactionId": "TXN-9", "amount": 750},
                policy=in_effect.policy,
                signals={
                    "refundEligible": True,
                    "fraudCheckPassed": True,
                    "refundAmount": 750,
                    "managerApproved": True,
                    "approvalArtifact": approval,
                },
            )


            declared = client.declare_transaction(transaction)


            # Nothing is released until this call.

            record =
            client.execute_transaction(declared.business_transaction_id)


            print(record.business_transaction_id,
            record.executions[0].decision.outcome)
components:
  schemas:
    execution-trust-record-response.schema:
      $ref: '#/components/schemas/execution-trust-record.schema'
      title: Execution Trust Record Response
      description: >-
        Response returned by POST /execute, POST /transactions, and GET
        /trust-records/{businessTransactionId}. A bare Execution Trust Record,
        no wrapper. POST /execute returns this with status 200; POST
        /transactions returns the identical shape with status 201.
    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
    execution-trust-record.schema:
      title: Execution Trust Record
      description: >-
        Canonical immutable record representing everything Parmana knows about a
        Business Transaction: the authoritative source for replay, verification,
        audit, and receipt generation. One Execution Trust Record exists per
        Business Transaction. overrides, executions, verifications, and receipts
        are append-only: existing entries are never modified or removed.
      type: object
      additionalProperties: true
      required:
        - trustRecordId
        - businessTransactionId
        - transaction
        - overrides
        - executions
        - verifications
        - receipts
        - trustRecordHash
        - signature
        - createdAt
        - updatedAt
      properties:
        trustRecordId:
          type: string
          description: Unique Execution Trust Record identifier.
        businessTransactionId:
          type: string
          description: Business Transaction identifier.
        transaction:
          $ref: '#/components/schemas/business-transaction.schema'
        overrides:
          type: array
          description: >-
            Override history. Append-only; empty on every transaction in this
            repository today (no route creates an Override).
          items:
            $ref: '#/components/schemas/override.schema'
        executions:
          type: array
          description: Execution history. Append-only.
          items:
            $ref: '#/components/schemas/execution.schema'
        verifications:
          type: array
          description: Verification history. Append-only.
          items:
            $ref: '#/components/schemas/verification.schema'
        receipts:
          type: array
          description: Receipt history. Append-only.
          items:
            $ref: '#/components/schemas/receipt.schema'
        trustRecordHash:
          type: string
          description: >-
            Canonical hash of the Execution Trust Record, computed over its
            canonical serialized form.
        signature:
          type: object
          description: >-
            Cryptographic signature over the canonical Execution Trust Record,
            proving it was produced by Parmana and has not been modified since
            signing.
          additionalProperties: true
          required:
            - algorithm
            - keyId
            - value
            - signedAt
          properties:
            algorithm:
              type: string
              examples:
                - ed25519
            keyId:
              type: string
              description: Identifier of the signing key.
            value:
              type: string
              description: Base64-encoded signature value.
            signedAt:
              type: string
              format: date-time
        createdAt:
          type: string
          format: date-time
          description: UTC timestamp when the Execution Trust Record was first created.
        updatedAt:
          type: string
          format: date-time
          description: >-
            UTC timestamp when the Execution Trust Record was last extended with
            a new immutable artifact.
        evidenceAnchor:
          type: object
          description: >-
            Explicit binding linking policy-governance provenance
            (transaction.policy.contentHash/governanceAnchor) to what a
            connector actually did (executions[].evidence.attributes.connector).
            Not a new cryptographic guarantee on its own -- both were already
            covered by trustRecordHash/signature -- but a single,
            explicitly-named pointer an auditor can check without reconstructing
            the binding themselves. Absent on a Trust Record built before this
            field existed.
          additionalProperties: false
          required:
            - anchorHash
          properties:
            policyContentHash:
              type: string
              description: >-
                Copied from transaction.policy.contentHash (G-24). Present on
                every real Execution Trust Record.
            governanceAnchorStatus:
              type: string
              enum:
                - VERIFIED
                - NO_APPROVAL_RECORD
                - SIGNATURE_INVALID
                - CONTENT_MISMATCH
              description: >-
                Copied from transaction.policy.governanceAnchor.status (G-45).
                Absent only when no governance anchor resolver was configured
                for this deployment.
            connectorEvidenceHash:
              type: string
              description: >-
                Copied from
                executions[0].evidence.attributes.connector.connectorEvidenceHash,
                when a real connector executed.
            anchorHash:
              type: string
              description: >-
                sha256 of the canonicalized {policyContentHash,
                governanceAnchorStatus, connectorEvidenceHash} above.
      examples:
        - trustRecordId: 759e916e-66d2-48c3-8869-55d557acf155
          businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
          transaction:
            businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
            metadata:
              businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
              correlationId: 6b97caca-1605-4711-bf00-7e5a65434d93
              sourceSystem: vendor-payment-service
              submittedBy: ap-automation
              submittedAt: '2026-07-07T16:38:59.285Z'
            authority:
              authorityId: c0c01c23-04a2-45f2-a821-ef24bfca02d3
              authorityType: SERVICE
              principalId: ap-automation-svc
              displayName: Accounts Payable Automation
              issuedAt: '2026-07-07T16:38:59.285Z'
            authorization:
              authorizationId: 6e9d6aa6-6d20-40a8-b05d-383516365cc7
              authorityId: c0c01c23-04a2-45f2-a821-ef24bfca02d3
              purpose: Authorize vendor payment disbursement
              issuedAt: '2026-07-07T16:38:59.285Z'
            intent:
              intentId: ae5865f6-181b-409a-90ec-1b4b8b8414ba
              authorizationId: 6e9d6aa6-6d20-40a8-b05d-383516365cc7
              action: payments:execute
              target: vendor/V-100
              parameters:
                amount: 4500
                currency: USD
              createdAt: '2026-07-07T16:38:59.285Z'
            policy:
              name: vendor-payment
              version: 2.0.0
              schemaVersion: 1.0.0
            signals:
              vendorVerified: true
              invoiceVerified: true
              paymentApproved: true
              sufficientFunds: true
              paymentAmount: 4500
              riskScore: 10
            status: RECEIVED
            createdAt: '2026-07-07T16:38:59.325Z'
          overrides: []
          executions:
            - executionId: 2be38c15-f93c-4621-9a1c-7570c130dea0
              businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
              decision:
                decisionId: 9d69dc0b-333a-4be3-b09f-358fece806f3
                intentId: ae5865f6-181b-409a-90ec-1b4b8b8414ba
                policy:
                  name: vendor-payment
                  version: 2.0.0
                  schemaVersion: 1.0.0
                signals:
                  vendorVerified: true
                  invoiceVerified: true
                  paymentApproved: true
                  sufficientFunds: true
                  paymentAmount: 4500
                  riskScore: 10
                outcome: APPROVED
                reason: >-
                  Vendor payment authorized. Vendor verification, invoice
                  verification, payment approval, funding, and risk assessment
                  requirements were satisfied.
                evaluatedAt: '2026-07-07T16:38:59.326Z'
              status: COMPLETED
              mode: SYNC
              startedAt: '2026-07-07T16:38:59.328Z'
              metadata:
                authorizationId: 1dc2d137-fde2-4d9c-b298-79e9f8a0d03e
              evidence:
                businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
                action: payments:execute
                target: vendor/V-100
                parameters:
                  amount: 4500
                  currency: USD
                success: true
                executedAt: '2026-07-07T16:38:59.328Z'
                attributes:
                  connector:
                    connectorId: vendor-payment
                    connectorVersion: 1.0.0
                    capability: payments:execute
                    sanitizedEndpoint: vendor/V-100
                    credentialProviderId: environment
                    requestSummary:
                      businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
                      action: payments:execute
                      target: vendor/V-100
                      parameters:
                        amount: 4500
                        currency: USD
                    responseSummary:
                      success: true
                      metadata: {}
                    startedAt: '2026-07-07T16:38:59.328Z'
                    completedAt: '2026-07-07T16:38:59.328Z'
                    connectorEvidenceHash: >-
                      7bcacb3e399a713e44a4f48aa2783de8060ae28591e4fc1256b504bd32cd7aea
              completedAt: '2026-07-07T16:38:59.329Z'
          verifications:
            - verificationId: 0b96c8b4-9cd8-4162-81fc-086575cf0924
              businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
              status: VERIFIED
              message: Execution Trust Record verified successfully.
              verifiedAt: '2026-07-07T16:38:59.331Z'
              trustRecordHash: 989aef83d595202ec02bb338ac00461abec0541098ea065f965b5cde342d3b25
          receipts:
            - receiptId: 3073a598-f927-4caf-8bb8-4f083f62b7e9
              businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
              trustRecordHash: 989aef83d595202ec02bb338ac00461abec0541098ea065f965b5cde342d3b25
              receiptHash: 8a5a0e9255dafef5ec588f0834e3c5b81dc7feb98a59f8bfa7083438fa58e231
              issuedAt: '2026-07-07T16:38:59.331Z'
              algorithm: ed25519
              signature: >-
                vzpykBuJhoy/2BdiR1x02KYZqMtKJu39olRJdzM5veSo9nYmoNSYQnt9HELlb2jlGWf07jPhP8ZXlrQnN4KQBA==
          createdAt: '2026-07-07T16:38:59.329Z'
          updatedAt: '2026-07-07T16:38:59.329Z'
          trustRecordHash: 989aef83d595202ec02bb338ac00461abec0541098ea065f965b5cde342d3b25
          signature:
            algorithm: ed25519
            keyId: default
            value: >-
              l41lr6nCUbrzEfoil/3+gkXd4zEQ9TR1qFaSwLuE70L/9U6cVz3VXdM1lPsDfELKh6RO4qcDrFWF/S3k4CAxAQ==
            signedAt: '2026-07-07T16:38:59.330Z'
    business-transaction.schema:
      title: Business Transaction
      description: >-
        Canonical immutable business context accepted by Parmana for execution:
        Authority -> Authorization -> Intent -> Business Transaction -> Policy.
        Every Business Transaction produces exactly one Decision, one Execution,
        and one Execution Trust Record.
      type: object
      additionalProperties: true
      required:
        - businessTransactionId
        - metadata
        - authority
        - authorization
        - intent
        - policy
        - signals
        - status
        - createdAt
      properties:
        businessTransactionId:
          type: string
          format: uuid
          description: >-
            Unique Business Transaction identifier. Same value as
            metadata.businessTransactionId. Must be a valid UUID on both POST
            /execute and POST /transactions (rejected with a 400 otherwise).
          x-default: 8ddd9ae9-eebe-4a5a-8182-4e6187466a74
        metadata:
          $ref: '#/components/schemas/metadata.schema'
        authority:
          $ref: '#/components/schemas/authority.schema'
        authorization:
          $ref: '#/components/schemas/authorization.schema'
        intent:
          $ref: '#/components/schemas/intent.schema'
        policy:
          $ref: '#/components/schemas/policy.schema'
        signals:
          $ref: '#/components/schemas/signals.schema'
        status:
          type: string
          description: >-
            Current Business Transaction lifecycle state. Always RECEIVED at
            creation on both POST /execute and POST /transactions. Parmana sets
            this field via BusinessTransactionMapper.fromRequest and ignores any
            status the client sends.
          enum:
            - RECEIVED
            - POLICY_EVALUATED
            - APPROVED
            - REJECTED
            - OVERRIDDEN
            - EXECUTING
            - EXECUTED
            - FAILED
            - VERIFIED
        createdAt:
          type: string
          format: date-time
          description: UTC timestamp when the Business Transaction was accepted by Parmana.
      examples:
        - businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
          metadata:
            businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
            correlationId: 6b97caca-1605-4711-bf00-7e5a65434d93
            sourceSystem: vendor-payment-service
            submittedBy: ap-automation
            submittedAt: '2026-07-07T16:38:59.285Z'
          authority:
            authorityId: c0c01c23-04a2-45f2-a821-ef24bfca02d3
            authorityType: SERVICE
            principalId: ap-automation-svc
            displayName: Accounts Payable Automation
            issuedAt: '2026-07-07T16:38:59.285Z'
          authorization:
            authorizationId: 6e9d6aa6-6d20-40a8-b05d-383516365cc7
            authorityId: c0c01c23-04a2-45f2-a821-ef24bfca02d3
            purpose: Authorize vendor payment disbursement
            issuedAt: '2026-07-07T16:38:59.285Z'
          intent:
            intentId: ae5865f6-181b-409a-90ec-1b4b8b8414ba
            authorizationId: 6e9d6aa6-6d20-40a8-b05d-383516365cc7
            action: payments:execute
            target: vendor/V-100
            parameters:
              amount: 4500
              currency: USD
            createdAt: '2026-07-07T16:38:59.285Z'
          policy:
            name: vendor-payment
            version: 2.0.0
            schemaVersion: 1.0.0
          signals:
            vendorVerified: true
            invoiceVerified: true
            paymentApproved: true
            sufficientFunds: true
            paymentAmount: 4500
            riskScore: 10
          status: RECEIVED
          createdAt: '2026-07-07T16:38:59.325Z'
    override.schema:
      title: Override
      description: >-
        Immutable trust artifact recording an authorized human override for a
        Business Transaction. No API route in this repository currently creates
        an Override; this schema exists only because
        ExecutionTrustRecord.overrides is part of the append-only Trust Record
        shape; every captured example has an empty overrides array.
      type: object
      additionalProperties: true
      required:
        - overrideId
        - businessTransactionId
        - approvedBy
        - reason
        - approvedAt
      properties:
        overrideId:
          type: string
          description: Unique Override identifier.
        businessTransactionId:
          type: string
          description: Business Transaction to which this Override belongs.
        approvedBy:
          type: string
          description: Authorized user or system that approved the Override.
        reason:
          type: string
          description: Human-readable reason for the Override.
        justification:
          type: string
          description: Optional business justification.
        approvedAt:
          type: string
          format: date-time
          description: UTC timestamp when the Override was approved.
    execution.schema:
      title: Execution
      description: >-
        Immutable trust artifact recording what actually happened while
        processing a Business Transaction. Every Execution records exactly one
        Decision produced by deterministic Policy evaluation.
      type: object
      additionalProperties: true
      required:
        - executionId
        - businessTransactionId
        - decision
        - status
        - mode
        - startedAt
      properties:
        executionId:
          type: string
          description: Unique Execution identifier.
        businessTransactionId:
          type: string
          description: Business Transaction to which this Execution belongs.
        decision:
          $ref: '#/components/schemas/decision.schema'
        status:
          type: string
          description: Execution lifecycle state.
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
        mode:
          type: string
          description: Execution mode.
          enum:
            - SYNC
            - ASYNC
        startedAt:
          type: string
          format: date-time
          description: UTC timestamp when execution started.
        completedAt:
          type: string
          format: date-time
          description: >-
            UTC timestamp when execution completed. Present only for terminal
            executions.
        evidence:
          type: object
          description: >-
            Immutable execution evidence: businessTransactionId, action, target,
            parameters, success, executedAt, and an optional attributes bag for
            execution-system-specific evidence (for example Connector SDK
            evidence, when a Connector executed this Execution).
          additionalProperties: true
        metadata:
          type: object
          description: >-
            Execution-specific metadata. Currently populated with
            authorizationId when the Execution is APPROVED.
          additionalProperties: true
      examples:
        - executionId: 90746492-7721-4228-b244-67bf8a45ca68
          businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e
          decision:
            decisionId: 8ec880cb-677a-4889-96f1-5a18a4edc1b5
            intentId: 1e77d0b3-2e57-4e31-b780-03abc92f1b69
            policy:
              name: vendor-payment
              version: 2.0.0
              schemaVersion: 1.0.0
            signals:
              vendorVerified: true
              invoiceVerified: true
              paymentApproved: true
              sufficientFunds: true
              paymentAmount: 5000
              riskScore: 12
            outcome: APPROVED
            reason: >-
              Vendor payment authorized. Vendor verification, invoice
              verification, payment approval, funding, and risk assessment
              requirements were satisfied.
            evaluatedAt: '2026-07-13T17:36:00.967Z'
          status: COMPLETED
          mode: SYNC
          startedAt: '2026-07-13T17:36:00.968Z'
          metadata:
            authorizationId: dbc09266-2078-4d4e-93d0-f355eb7eebcc
          evidence:
            businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e
            action: payments:execute
            target: vendor/V-500
            parameters:
              amount: 5000
              currency: USD
            success: true
            executedAt: '2026-07-13T17:36:00.970Z'
            attributes:
              connector:
                connectorId: vendor-payment
                connectorVersion: 1.0.0
                capability: payments:execute
                sanitizedEndpoint: vendor/V-500
                credentialProviderId: environment
                requestSummary:
                  businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e
                  action: payments:execute
                  target: vendor/V-500
                  parameters:
                    amount: 5000
                    currency: USD
                responseSummary:
                  success: true
                  metadata: {}
                startedAt: '2026-07-13T17:36:00.970Z'
                completedAt: '2026-07-13T17:36:00.970Z'
                connectorEvidenceHash: >-
                  c97411026a82b608d9b0f8b137a64e26d8af24bdda09310b639e527e08a9aada
          completedAt: '2026-07-13T17:36:00.970Z'
    verification.schema:
      title: Verification
      description: >-
        Immutable result of verifying an entire Execution Trust Record:
        recomputed hash matches the stored hash, signature verifies, and every
        APPROVED Execution carries a non-empty authorizationId. All checks
        always run and are reported together in message; a failure in one does
        not skip the others.
      type: object
      additionalProperties: true
      required:
        - verificationId
        - businessTransactionId
        - status
        - verifiedAt
        - trustRecordHash
      properties:
        verificationId:
          type: string
          description: Unique Verification identifier.
        businessTransactionId:
          type: string
          description: Business Transaction being verified.
        status:
          type: string
          description: Verification result.
          enum:
            - VERIFIED
            - FAILED
        message:
          type: string
          description: >-
            Human-readable verification summary: either the success message, or
            every failed check's message joined with "; ".
        verifiedAt:
          type: string
          format: date-time
          description: UTC timestamp when verification completed.
        trustRecordHash:
          type: string
          description: >-
            Hash of the verified Execution Trust Record, proving exactly which
            record was verified.
      examples:
        - verificationId: 0ad69d3f-7fd0-4507-ab38-e386146757ae
          businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
          status: VERIFIED
          message: Execution Trust Record verified successfully.
          verifiedAt: '2026-07-07T16:38:59.344Z'
          trustRecordHash: 989aef83d595202ec02bb338ac00461abec0541098ea065f965b5cde342d3b25
    receipt.schema:
      title: Receipt
      description: >-
        Cryptographically signed, immutable Execution Trust Receipt proving the
        outcome of an Execution Trust Record at the time it was issued.
      type: object
      additionalProperties: true
      required:
        - receiptId
        - businessTransactionId
        - trustRecordHash
        - receiptHash
        - signature
        - algorithm
        - issuedAt
      properties:
        receiptId:
          type: string
          description: Unique Receipt identifier.
        businessTransactionId:
          type: string
          description: Business Transaction represented by this Receipt.
        executionId:
          type: string
          description: >-
            Execution represented by this Receipt. Absent when the Receipt
            represents the latest transaction state; every Receipt currently
            produced by ReceiptService omits this field.
        trustRecordHash:
          type: string
          description: >-
            Canonical hash of the Execution Trust Record, used for independent
            verification.
        receiptHash:
          type: string
          description: Hash of this Receipt.
        signature:
          type: string
          description: Base64-encoded digital signature over the Receipt.
        algorithm:
          type: string
          description: Signing algorithm.
          examples:
            - ed25519
        issuedAt:
          type: string
          format: date-time
          description: UTC timestamp when the Receipt was generated.
      examples:
        - receiptId: 312ce65d-8ec4-4978-ac50-aeb0062ad7be
          businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
          trustRecordHash: 989aef83d595202ec02bb338ac00461abec0541098ea065f965b5cde342d3b25
          receiptHash: 2cc963456dd71e0e85f2d2fe743d4475072997287356ac1b9c6a9314b189ea8b
          issuedAt: '2026-07-07T16:38:59.350Z'
          algorithm: ed25519
          signature: >-
            2Z49nDSXubFNTpy0ovPwguGW3IpgvdJuiusCAadMNPS4cqmjRUthZmrfN3kZUO5m7Ku5v/poeLxtjsFKvXe9DA==
    metadata.schema:
      title: Metadata
      description: >-
        Immutable Business Transaction metadata supplied by the calling
        application. Not evaluated by Policy. businessTransactionId is the only
        required field; it must match the top-level businessTransactionId.
        Parmana rejects a mismatch with a 400.
      type: object
      additionalProperties: true
      required:
        - businessTransactionId
      properties:
        businessTransactionId:
          type: string
          format: uuid
          description: Unique Business Transaction identifier. Must be a valid UUID.
        correlationId:
          type: string
          description: Optional correlation identifier used by the calling application.
        tenantId:
          type: string
          description: Optional tenant identifier for multi-tenant deployments.
        sourceSystem:
          type: string
          description: Originating application or service.
        submittedBy:
          type: string
          description: Identity of the calling application or principal.
        submittedAt:
          type: string
          format: date-time
          description: UTC timestamp when the Business Transaction was submitted.
      examples:
        - businessTransactionId: eed2a972-1bf5-4166-8472-761f76fbf1b2
          correlationId: 6b97caca-1605-4711-bf00-7e5a65434d93
          sourceSystem: vendor-payment-service
          submittedBy: ap-automation
          submittedAt: '2026-07-07T16:38:59.285Z'
    authority.schema:
      title: Authority
      description: >-
        Entity empowered to authorize execution within a trust domain. Immutable
        once issued.
      type: object
      additionalProperties: true
      required:
        - authorityId
        - authorityType
        - principalId
        - issuedAt
      properties:
        authorityId:
          type: string
          description: Unique Authority identifier.
        authorityType:
          type: string
          description: Type of authority.
          enum:
            - USER
            - ROLE
            - SERVICE
            - ORGANIZATION
        principalId:
          type: string
          description: Principal identifier.
        displayName:
          type: string
          description: Human-readable display name.
        issuedAt:
          type: string
          format: date-time
          description: UTC timestamp when Authority became effective.
      examples:
        - authorityId: c0c01c23-04a2-45f2-a821-ef24bfca02d3
          authorityType: SERVICE
          principalId: ap-automation-svc
          displayName: Accounts Payable Automation
          issuedAt: '2026-07-07T16:38:59.285Z'
    authorization.schema:
      title: Authorization
      description: >-
        Immutable trust artifact proving that an Authority granted approval for
        an intended execution.
      type: object
      additionalProperties: true
      required:
        - authorizationId
        - authorityId
        - purpose
        - issuedAt
      properties:
        authorizationId:
          type: string
          description: Unique Authorization identifier.
        authorityId:
          type: string
          description: >-
            Authority issuing this Authorization. Must match
            authority.authorityId. Parmana rejects a mismatch with a 400.
        purpose:
          type: string
          description: Business purpose for which the Authorization was granted.
        issuedAt:
          type: string
          format: date-time
          description: UTC timestamp when the Authorization was issued.
        expiresAt:
          type: string
          format: date-time
          description: >-
            Optional expiration timestamp. After this time the Authorization is
            no longer valid.
      examples:
        - authorizationId: 6e9d6aa6-6d20-40a8-b05d-383516365cc7
          authorityId: c0c01c23-04a2-45f2-a821-ef24bfca02d3
          purpose: Authorize vendor payment disbursement
          issuedAt: '2026-07-07T16:38:59.285Z'
    intent.schema:
      title: Intent
      description: >-
        Immutable declaration of the action an Authority intends to be executed
        under an Authorization.
      type: object
      additionalProperties: true
      required:
        - intentId
        - authorizationId
        - action
        - target
        - parameters
        - createdAt
      properties:
        intentId:
          type: string
          description: Unique Intent identifier.
        authorizationId:
          type: string
          description: >-
            Authorization under which this Intent was created. Must match
            authorization.authorizationId. Parmana rejects a mismatch with a
            400.
        action:
          type: string
          description: >-
            Business action being requested. Required and non-empty. Parmana
            rejects an empty action with a 400.
          examples:
            - VendorPayment
            - TransferFunds
            - DeployApplication
        target:
          type: string
          description: Target of the intended action.
          examples:
            - vendor/V-100
            - account/12345
        parameters:
          type: object
          description: >-
            Immutable business parameters describing the intended action. Not
            evaluated by policy, see signals.
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          description: UTC timestamp when the Intent was created.
      examples:
        - intentId: ae5865f6-181b-409a-90ec-1b4b8b8414ba
          authorizationId: 6e9d6aa6-6d20-40a8-b05d-383516365cc7
          action: payments:execute
          target: vendor/V-100
          parameters:
            amount: 4500
            currency: USD
          createdAt: '2026-07-07T16:38:59.285Z'
    policy.schema:
      title: Policy Reference
      description: >-
        Exact Policy to evaluate. The client explicitly supplies name, version,
        and schemaVersion; Parmana does not automatically discover or select a
        policy. If no matching policy file exists at
        policies/{name}/{version}/policy.json, the request fails with a 404
        (policyId/policyVersion on POST /policies/validate) or a RUNTIME_ERROR
        (name/version elsewhere, from PolicyNotFoundError not otherwise mapped
        by the shared error handler in every route, see the error envelope
        note).
      type: object
      additionalProperties: true
      required:
        - name
        - version
        - schemaVersion
      properties:
        name:
          type: string
          description: >-
            Policy name. Required and non-empty. Parmana rejects an empty name
            with a 400.
          minLength: 1
        version:
          type: string
          description: >-
            Business policy version. Required and non-empty. Parmana rejects an
            empty version with a 400.
          minLength: 1
          examples:
            - 2.0.0
            - 1.0.0
        schemaVersion:
          type: string
          description: Signals schema version expected by the policy.
          examples:
            - 1.0.0
        contentHash:
          type: string
          description: >-
            sha256 of the canonicalized policy.json content actually loaded for
            this decision (G-24). Server-computed, never caller-settable; absent
            on a request-supplied PolicyReference and on a PolicyReference built
            before this field existed. Only present on the copy embedded in an
            Execution Trust Record's transaction.policy.
        governanceAnchor:
          type: object
          description: >-
            Whether the policy content above is traceable to a completed Policy
            Governance approval, resolved at decision time (G-45). Absent on a
            PolicyReference built before this field existed. Its presence does
            not imply POLICY_EXECUTION_VERIFICATION_ENFORCED is on -- only that
            the lookup ran and recorded what it found, which may honestly be "no
            approval record exists for this policy yet."
          additionalProperties: false
          required:
            - status
          properties:
            status:
              type: string
              enum:
                - VERIFIED
                - NO_APPROVAL_RECORD
                - SIGNATURE_INVALID
                - CONTENT_MISMATCH
            approvalRecordId:
              type: string
              description: >-
                The PolicyChangeApprovalRecord this anchor resolved against.
                Present only when a record was found at all -- absent for
                NO_APPROVAL_RECORD.
      examples:
        - name: vendor-payment
          version: 2.0.0
          schemaVersion: 1.0.0
        - name: vendor-payment
          version: 2.0.0
          schemaVersion: 1.0.0
          contentHash: 3f2504e04f8964e7ad0dbb0cf7fea1b4e0e1e0a3a1e1a4b6c8e0d5f6a7b8c9d0
          governanceAnchor:
            status: NO_APPROVAL_RECORD
    signals.schema:
      title: Signals
      description: >-
        Opaque runtime facts evaluated by the resolved Policy's rules. Parmana
        assigns no business meaning to these values and does not statically
        validate them beyond the Policy's own signalsSchema declaration (see
        policies/{name}/{version}/policy.json). Scaled integers, not floats, for
        numeric signals such as amounts (house convention across every reference
        policy).
      type: object
      additionalProperties: true
      examples:
        - vendorVerified: true
          invoiceVerified: true
          paymentApproved: true
          sufficientFunds: true
          paymentAmount: 4500
          riskScore: 10
    decision.schema:
      title: Decision
      description: >-
        Immutable result of evaluating an Intent against a Policy. Decision does
        not create authority, grant authorization, or modify Intent; it only
        records the outcome of deterministic Policy evaluation.
      type: object
      additionalProperties: true
      required:
        - decisionId
        - intentId
        - policy
        - signals
        - outcome
        - evaluatedAt
      properties:
        decisionId:
          type: string
          description: Unique Decision identifier.
        intentId:
          type: string
          description: Intent evaluated by this Decision.
        policy:
          $ref: '#/components/schemas/policy.schema'
        signals:
          $ref: '#/components/schemas/signals.schema'
        outcome:
          type: string
          description: >-
            Policy evaluation outcome. There are no intermediate states: a
            Decision is always exactly one of these two values.
          enum:
            - APPROVED
            - REJECTED
        reason:
          type: string
          description: >-
            Human-readable explanation, taken from the matching Policy rule's
            outcome.reason.
        matchedRuleId:
          type: string
          description: >-
            Identifier of the Policy rule that matched, or "none" when no rule
            matched. Absent on a Decision built before this field existed
            (docs/internal/VERIFICATION-GAPS.md G-44).
        evaluatedRules:
          type: integer
          description: >-
            Number of rules evaluated before reaching a match (or exhausting the
            rule list). Same optionality as matchedRuleId.
        matchedPath:
          type: array
          items:
            type: string
          description: >-
            Ordered rule-id trace evaluation walked to reach matchedRuleId. Same
            optionality as matchedRuleId.
        evaluatedAt:
          type: string
          format: date-time
          description: UTC timestamp when policy evaluation completed.
        assessment:
          type: object
          description: >-
            Authority, business validation and, for a refusal, execution, each
            as its own status (RFC-0023). AUTHORIZED means the action type may
            be decided, not that this action is valid or was executed. Absent on
            decisions made before it existed.
          required:
            - authority
            - businessValidation
          properties:
            authority:
              type: object
              required:
                - status
                - reason
              properties:
                status:
                  type: string
                  enum:
                    - AUTHORIZED
                    - NOT_AUTHORIZED
                    - AUTHORITY_UNCLEAR
                    - AUTHORITY_EXPIRED
                reason:
                  type: string
            businessValidation:
              type: object
              required:
                - status
                - reason
              properties:
                status:
                  type: string
                  enum:
                    - VALID
                    - INVALID
                    - MISSING_DATA
                    - CONFLICTING_DATA
                    - SOURCE_UNAVAILABLE
                    - VALIDATION_EXPIRED
                    - NOT_EVALUATED
                reason:
                  type: string
                signals:
                  type: array
                  description: >-
                    Trusted Signals: facts established by their sources for this
                    exact business object and action.
                  items:
                    type: object
                failures:
                  type: array
                  description: >-
                    Why business validation did not pass, one entry per signal
                    that failed.
                  items:
                    type: object
                    required:
                      - signalKey
                      - status
                      - reason
                    properties:
                      signalKey:
                        type: string
                      status:
                        type: string
                        enum:
                          - VALID
                          - INVALID
                          - MISSING_DATA
                          - CONFLICTING_DATA
                          - SOURCE_UNAVAILABLE
                          - VALIDATION_EXPIRED
                          - NOT_EVALUATED
                      reason:
                        type: string
            execution:
              type: object
              required:
                - status
                - reason
              properties:
                status:
                  type: string
                  enum:
                    - EXECUTED
                    - NOT_EXECUTED
                    - EXECUTION_FAILED
                    - EXECUTION_UNKNOWN
                reason:
                  type: string
      examples:
        - decisionId: 9d69dc0b-333a-4be3-b09f-358fece806f3
          intentId: ae5865f6-181b-409a-90ec-1b4b8b8414ba
          policy:
            name: vendor-payment
            version: 2.0.0
            schemaVersion: 1.0.0
          signals:
            vendorVerified: true
            invoiceVerified: true
            paymentApproved: true
            sufficientFunds: true
            paymentAmount: 4500
            riskScore: 10
          outcome: APPROVED
          reason: >-
            Vendor payment authorized. Vendor verification, invoice
            verification, payment approval, funding, and risk assessment
            requirements were satisfied.
          matchedRuleId: approve-payment
          evaluatedRules: 1
          matchedPath:
            - approve-payment
          evaluatedAt: '2026-07-07T16:38:59.326Z'
  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
    SigningUnavailable:
      description: >-
        Refused before release: nothing was executed. `SIGNING_UNAVAILABLE`: the
        server could not prove it can sign a Trust Record. `AUDIT_UNAVAILABLE`:
        the caller audit trail could not be written.
        `EXECUTION_INTENT_UNAVAILABLE`: the signed Execution Intent could not be
        stored. For these three, retry later with a new `businessTransactionId`,
        because the first one was already accepted. `CONNECTOR_NOT_REGISTERED`:
        no connector is configured for this action on this deployment; the
        operator must configure it before any retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.schema'
          examples:
            executionIntentUnavailable:
              summary: >-
                The signed Execution Intent could not be stored, nothing was
                executed (real captured response)
              value:
                error: >-
                  The signed Execution Intent for business transaction
                  '2c3cae0f-fd3c-4962-8147-83f3710a2fc9' could not be created
                  and stored; refusing to release the action. Nothing was
                  executed. Cause: new row for relation "execution_intents"
                  violates check constraint "sbx_block_intents"
                code: EXECUTION_INTENT_UNAVAILABLE
            signingUnavailable:
              summary: Evidence signing is unhealthy, nothing was executed
              value:
                error: >-
                  Evidence signing is unavailable; refusing to release the
                  action because a signed Execution Trust Record could not be
                  produced. Nothing was executed.
                code: SIGNING_UNAVAILABLE
            auditUnavailable:
              summary: The caller audit trail could not be written
              value:
                error: >-
                  Caller authentication audit trail is unavailable; refusing to
                  proceed without an audit record.
                code: AUDIT_UNAVAILABLE
            connectorNotRegistered:
              summary: No connector is registered for the action, nothing was executed
              value:
                error: >-
                  No connector is registered for capability 'erp:invoice-pay' on
                  this deployment. Nothing was executed. The operator must
                  configure the connector.
                code: CONNECTOR_NOT_REGISTERED
  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.