> ## 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 Business Transaction > Runs the complete pipeline synchronously and returns the finished Execution Trust Record. ## OpenAPI ````yaml openapi.bundled.yaml POST /execute openapi: 3.1.0 info: title: Parmana API version: 1.0.0 description: > Parmana is an Execution Trust Infrastructure that ensures there is no gap between what humans decide and what AI systems do. The API enables creation, execution, verification, replay, and auditing of Business Transactions through cryptographically verifiable Execution Trust Records. **Every route requires a caller bearer key**, except the liveness/readiness probes and documentation/verification routes that must be reachable with no credential: GET /health, GET /ready, GET /openapi.yaml, GET /documentation, GET /reference, POST /refusal/verify, POST /audit/verify, GET /keys/{keyId}, and GET /.well-known/jwks.json. Send `Authorization: Bearer ` on every other request. Keys are issued by `scripts/generate-api-key.ts` and configured server-side via `PARMANA_API_KEYS`; only a hash of each key is ever held by the server, verified in constant time. A missing or invalid credential returns 401 before a Business Transaction is even constructed, independent of Policy evaluation and gateway attestation, see `packages/api/src/middleware/caller-auth.ts` and [Authentication](/api-reference/authentication). Local development may set `PARMANA_AUTH_DISABLED=true` to skip this middleware entirely; that flag must never be set in a real deployment. contact: name: Parmana Systems email: founder@parmanasystems.com license: name: Proprietary, source-available for evaluation only, see LICENSE url: https://github.com/pavancharak/AgentLabsBuildathon/blob/main/LICENSE servers: - url: https://parmana-api-real.vercel.app description: >- Production (real, deployed instance -- the docs site playground uses this by default) - 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: Refusal Records description: >- Durable, signed evidence that a policy decision rejected a transaction (RFC-0021) - name: Audit description: >- Signed caller-authentication audit events, independently third-party-verifiable - name: System description: Operational endpoints paths: /execute: post: tags: - Execution summary: Execute a Business Transaction description: > Runs the complete pipeline synchronously and returns the finished Execution Trust Record. In order, the server accepts and stores the Business Transaction, evaluates the policy, signs an authorization for an approved action and releases it to the connector, then builds, signs and verifies the record and generates a receipt. `businessTransactionId` must be a valid UUID (v1 to v5). It is the idempotency key: sending the same one again returns `409`. The server assigns `status` and `createdAt`, sets `metadata.submittedBy` from the authenticated key, and drops any top level field that is not in the request schema. Which `intent.action` values work depends on the connectors registered on the server. An action with no registered connector fails with a `500`. How each outcome is reported: 1. `200`: approved and released. The body is the signed Execution Trust Record. 2. `403` with code `POLICY_DENIED`: a policy refused. This is final and nothing was released. 3. `403` with code `CAPABILITY_NOT_ALLOWED`, or with no code: the key may not invoke the action, or may not assert that principal. 4. `429`: rate limited. Nothing was recorded. Wait for the `Retry-After` header. 5. `503` with code `SIGNING_UNAVAILABLE` or `AUDIT_UNAVAILABLE`: refused before release. Nothing was executed. 6. `500` with code `EXECUTION_RECORD_INCOMPLETE`: the action was released but its signed record could not be produced. Do not resubmit under a new id. The examples named `vendor-payment-flow` are historical captures that show the response shape. The `payments:execute` action they use no longer exists on a current server. See the [Error catalog](/api-reference/error-catalog) and [Integrate Parmana: specification for AI agents](/agents/integrate). operationId: executeTransaction requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/transaction-create-request.schema' examples: test-fixture-flow: summary: >- A request that runs on a server started with NODE_ENV=test, using the test only capability test:fixture-execute. It was captured live on 2026-09-14 and is approved. value: 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 signals: vendorVerified: true invoiceVerified: true paymentApproved: true sufficientFunds: true paymentAmount: 1000 riskScore: 5 vendorId: vendor://payments vendor-payment-flow: summary: >- Historical capture (vendor-payment 2.0.0, approved). The payments:execute action no longer exists on a current server. Shown for the response shape only. value: businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e metadata: businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e correlationId: cc1ca975-4935-4e9a-a591-8897af6b56fb sourceSystem: vendor-payment-service submittedBy: ap-automation submittedAt: '2026-07-13T17:36:00.835Z' authority: authorityId: db5c5260-bb4c-40a2-a081-2928b5fe7720 authorityType: SERVICE principalId: ap-automation-svc displayName: Accounts Payable Automation issuedAt: '2026-07-13T17:36:00.835Z' authorization: authorizationId: 63bdc429-14e4-4ef4-8007-f3c0c9564261 authorityId: db5c5260-bb4c-40a2-a081-2928b5fe7720 purpose: Authorize vendor payment disbursement issuedAt: '2026-07-13T17:36:00.835Z' intent: intentId: 1e77d0b3-2e57-4e31-b780-03abc92f1b69 authorizationId: 63bdc429-14e4-4ef4-8007-f3c0c9564261 action: payments:execute target: vendor/V-500 parameters: amount: 5000 currency: USD createdAt: '2026-07-13T17:36:00.835Z' 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 responses: '200': description: >- Execution Trust pipeline completed. The Execution Trust Record reflects whatever the Decision outcome was. This status code does not by itself mean the payment was approved. content: application/json: schema: $ref: '#/components/schemas/execution-trust-record.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' vendor-payment-flow: summary: Real captured response value: trustRecordId: 65fee934-532c-4feb-88d9-72c0cd912a81 businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e transaction: businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e metadata: businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e correlationId: cc1ca975-4935-4e9a-a591-8897af6b56fb sourceSystem: vendor-payment-service submittedBy: ap-automation submittedAt: '2026-07-13T17:36:00.835Z' authority: authorityId: db5c5260-bb4c-40a2-a081-2928b5fe7720 authorityType: SERVICE principalId: ap-automation-svc displayName: Accounts Payable Automation issuedAt: '2026-07-13T17:36:00.835Z' authorization: authorizationId: 63bdc429-14e4-4ef4-8007-f3c0c9564261 authorityId: db5c5260-bb4c-40a2-a081-2928b5fe7720 purpose: Authorize vendor payment disbursement issuedAt: '2026-07-13T17:36:00.835Z' intent: intentId: 1e77d0b3-2e57-4e31-b780-03abc92f1b69 authorizationId: 63bdc429-14e4-4ef4-8007-f3c0c9564261 action: payments:execute target: vendor/V-500 parameters: amount: 5000 currency: USD createdAt: '2026-07-13T17:36:00.835Z' 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 status: RECEIVED createdAt: '2026-07-13T17:36:00.965Z' overrides: [] executions: - 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' verifications: - verificationId: e22354e0-7f22-49b2-bd2f-09e47881d788 businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e status: VERIFIED message: Execution Trust Record verified successfully. verifiedAt: '2026-07-13T17:36:00.973Z' trustRecordHash: >- e20a8861864f1a0a6c5fe00e64abca04de18a7d165a82ef9d7beb458c2096b3f receipts: - receiptId: 863947e6-9d36-492e-b9c9-78b0f3e9b6df businessTransactionId: 44b34a79-e0f2-49d7-a48e-e52fff88182e trustRecordHash: >- e20a8861864f1a0a6c5fe00e64abca04de18a7d165a82ef9d7beb458c2096b3f receiptHash: >- c9666b08b42bb5ff77650b544c3c2183609f25e4d8dc09359b71a970c57ed3ce issuedAt: '2026-07-13T17:36:00.973Z' algorithm: ed25519 signature: >- Pcr42EvbaUbLogvVhYiV3g7uuwvZr82HUJhVptnXRxmTtiEGiz2SCdz5Z80xRDvmvSxpOSG5OnvMAaRzJXncBg== createdAt: '2026-07-13T17:36:00.971Z' updatedAt: '2026-07-13T17:36:00.971Z' trustRecordHash: >- e20a8861864f1a0a6c5fe00e64abca04de18a7d165a82ef9d7beb458c2096b3f signature: algorithm: ed25519 keyId: default value: >- gjDYmHUBKIrv7bT3uwAkt3wHeoSwz5uANXQV5MfsFgbUIh83KiufZwxht3F3Een+7K/ZW9SRn0F0J7ACJRLbAg== signedAt: '2026-07-13T17:36:00.972Z' '400': description: >- businessTransactionId missing/malformed, or a Business Transaction trust-chain invariant failed (BusinessTransactionValidationError). content: application/json: schema: $ref: '#/components/schemas/error.schema' examples: badUuid: summary: Real captured response, malformed businessTransactionId value: error: businessTransactionId must be a valid UUID. '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Three distinct denials share this status. (1) Code POLICY_DENIED: a policy rejected the transaction, this is a final decision, do not retry the same request. (2) Code CAPABILITY_NOT_ALLOWED: the authenticated key is not permitted to invoke this transaction.intent.action (isCapabilityAllowed, an unset or empty allowedCapabilities denies everything). (3) No code: transaction.authority.principalId is missing/empty, or the authenticated caller is not permitted to assert it: isPrincipalAllowed (packages/api/src/auth/isPrincipalAllowed.ts) requires principalId to equal the caller's own callerId when no allowedPrincipalIds is configured for that key, or to appear in allowedPrincipalIds when one is. Checked immediately after caller authentication, before metadata.submittedBy is server-set and before any Policy evaluation. Skipped entirely (no 403 possible) when caller authentication itself is disabled. Identical check on POST /transactions, live-verified on both routes. 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: >- transaction.policy.name/version does not match any published Policy (PolicyNotFoundError, thrown by PolicyRouter.load during Runtime execution, reachable identically from POST /transactions, since both share the same application.execute() pipeline). 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: >- A Business Transaction with this businessTransactionId already exists (DuplicateBusinessTransactionError). content: application/json: schema: $ref: '#/components/schemas/error.schema' examples: duplicate: summary: Real captured response value: error: >- Business Transaction 'eed2a972-1bf5-4166-8472-761f76fbf1b2' already exists. '429': $ref: '#/components/responses/RateLimited' '500': description: >- Server failure. Covers these conditions. Code EXECUTION_RECORD_INCOMPLETE: the action was released to the execution system but its signed Execution Trust Record could not be produced or persisted, so do not resubmit under a new businessTransactionId and reconcile against the connector and the execution audit events instead. No Connector registered for the request's action. A structurally incomplete request body (a valid-UUID businessTransactionId but missing required nested fields, e.g. metadata). A policy rejection is NOT a 500, it is a 403 with code POLICY_DENIED. **Regression, re-verified this pass:** the "no Connector registered" case previously reached the client as a coded RuntimeError (`{"error":"No connector registered for action: .","code":"RUNTIME_ERROR"}`). Live-triggered against the current server it no longer does. `ConnectorSdkRegistry.resolveCapability` (packages/connector-sdk/src/ConnectorRegistry.ts) now throws a raw, uncaught `Error: No connector registered for capability ''.` that the shared error handler's `instanceof RuntimeError` check does not match, so it falls through to the generic 500 branch: the caller sees only `{"error":"Internal Server Error"}`, no code, and the real message and capability name are visible only in the server's own log. This is the same failure shape as the structurally-incomplete-body case below, not the previously documented one. See the noConnectorRegistered example, and the accompanying report: this is listed as a product regression to fix in packages/connector-sdk/execution-control, not something this docs pass changes in code. content: application/json: schema: $ref: '#/components/schemas/error.schema' examples: executionRecordIncomplete: summary: >- The action was released but its signed record could not be produced value: error: >- The action for business transaction 'e54187e6-431f-4e1c-9c0e-ff2cb5d6d40a' was released to the execution system, but its signed Execution Trust Record could not be produced. Do not retry as a new transaction: reconcile against the connector and the execution audit events for this businessTransactionId. authorizationId: 381ef27a-0955-4085-9e5d-e4223fef2986. code: EXECUTION_RECORD_INCOMPLETE noConnectorRegistered: summary: >- Real captured response, action has no registered Connector. Regression: previously a coded RuntimeError, now an uncaught error collapsed into the generic 500 handler, see the description above. value: error: Internal Server Error malformedBody: summary: >- Real captured response, valid UUID but missing required nested fields (e.g. metadata); no code field, this is the generic 500 handler, not a typed RuntimeError value: error: Internal Server Error '503': $ref: '#/components/responses/SigningUnavailable' components: schemas: transaction-create-request.schema: title: Transaction Create Request description: >- Request payload for POST /execute and POST /transactions. status and createdAt are assigned by Parmana and must not be supplied by the client. Validation performed identically by both endpoints (each has its own inline businessTransactionId UUID check, then shares BusinessTransactionMapper.fromRequest and BusinessTransactionValidator): metadata.businessTransactionId must equal businessTransactionId; authorization.authorityId must equal authority.authorityId; intent.authorizationId must equal authorization.authorizationId; policy.name, policy.version, and intent.action must each be non-empty. No other structural validation is performed: authority, authorization, intent, policy, and signals objects are otherwise passed through as supplied, including any additional properties. type: object additionalProperties: true required: - businessTransactionId - metadata - authority - authorization - intent - policy - signals properties: businessTransactionId: type: string format: uuid description: >- Unique Business Transaction identifier. Must be a valid UUID on both POST /execute and POST /transactions (rejected with 400 otherwise). 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' 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 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' 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 - EXECUTION_RECORD_INCOMPLETE 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 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 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). 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== 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/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. 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: >- Missing or invalid caller credential (StaticKeyAuthenticator returned no identity). Real captured response, packages/api/src/middleware/caller-auth.ts. content: application/json: schema: $ref: '#/components/schemas/error.schema' examples: authRequired: summary: Real captured response, missing or invalid Authorization header value: error: authentication required RateLimited: description: >- The caller exceeded the per minute limit on this route (RATE_LIMIT_EXECUTE_PER_MINUTE, default 30 per authenticated caller). The request never reached the handler, so nothing was recorded or executed. Wait the number of seconds in the Retry-After header, then retry. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/error.schema' examples: rateLimited: summary: Rate limit exceeded value: error: Rate limit exceeded. Try again later. code: RATE_LIMITED SigningUnavailable: description: >- The action was refused BEFORE it was released, so nothing was executed. Code SIGNING_UNAVAILABLE: the runtime could not prove it can sign an Execution Trust Record. Code AUDIT_UNAVAILABLE: the caller authentication audit trail could not be written. In both cases retry later with a new businessTransactionId, because the original was already accepted. content: application/json: schema: $ref: '#/components/schemas/error.schema' examples: 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 securitySchemes: bearerAuth: type: http scheme: bearer description: > Caller API key issued by scripts/generate-api-key.ts. Sent as Authorization: Bearer . 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. ````