Execute a Business Transaction

Runs the complete Execution Trust pipeline synchronously: accepts the Business Transaction, executes it through the Runtime, verifies the resulting Execution Trust Record, generates a Receipt, then returns the complete, updated Execution Trust Record. businessTransactionId must be a valid UUID (v1-v5) or the request fails before any persistence with a 400. See BusinessTransactionMapper.fromRequest and isValidBusinessTransactionId in packages/api/src/routes/execute.ts. The mapper reconstructs the transaction field by field, so status and createdAt supplied by the client are always ignored (Parmana assigns RECEIVED and the current time), and any top-level field not in the request schema is silently dropped. POST /transactions applies the identical UUID check and mapper. See that endpoint below.

If Policy evaluation REJECTs the transaction, this endpoint currently responds 500 with a RUNTIME_ERROR-coded error envelope naming the rejection reason. See the 500 response below and the executeRejected example. This is real, observed behavior, not a designed contract; it is documented here because the spec must describe the API as implemented.

hubspot:deal-update and hubspot:deal-fetch are the real, currently-registered capabilities reachable through this same endpoint by this capability-based routing mechanism today. Registration is conditional on HUBSPOT_PRIVATE_APP_TOKEN being configured; if it is not, the connector is never registered and this action falls into the “no Connector registered” case documented under 500 below. See packages/api/tests/integration/hubspot-deal-update.integration.test.ts for the executable, real-request proof of the hubspot flow.

payments:execute (vendor-payment), shown in the vendor-payment-flow example below, was removed from the repository entirely — see docs/VERIFICATION-GAPS.md G-27 in the source repo. That example is a real request/response pair captured before the removal; resubmitting it against a current server no longer produces the shown APPROVED result; it falls into the “no Connector registered” case instead, since no connector — production or test — registers payments:execute any longer. It is retained here as a real, historical illustration of the response shape, not as a currently-runnable example. The vendor-payment/2.0.0 policy file itself is unaffected and still loads (see PolicyValidate below); only the connector that would have executed against it is gone.

POST /execute

Execute a Business Transaction

cURL

curl --request POST \
  --url http://localhost:3000/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
  }
}
'

200

vendor-payment-flow

{ "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" } }

Authorizations

Authorization · string · header · required

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 except GET /health. See /api-reference/authentication.

Body

application/json

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.

businessTransactionId · string<uuid> · required

Unique Business Transaction identifier. Must be a valid UUID on both POST /execute and POST /transactions (rejected with 400 otherwise).

metadata · Metadata · object · required

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.

Show child attributes

Example:

{
  "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 · Authority · object · required

Entity empowered to authorize execution within a trust domain. Immutable once issued.

Show child attributes

Example:

{
  "authorityId": "c0c01c23-04a2-45f2-a821-ef24bfca02d3",
  "authorityType": "SERVICE",
  "principalId": "ap-automation-svc",
  "displayName": "Accounts Payable Automation",
  "issuedAt": "2026-07-07T16:38:59.285Z"
}

authorization · Authorization · object · required

Immutable trust artifact proving that an Authority granted approval for an intended execution.

Show child attributes

Example:

{
  "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 · Intent · object · required

Immutable declaration of the action an Authority intends to be executed under an Authorization.

Show child attributes

Example:

{
  "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 · Policy Reference · object · required

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

Show child attributes

Example:

{
  "name": "vendor-payment",
  "version": "2.0.0",
  "schemaVersion": "1.0.0"
}

signals · Signals · object · required

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

Example:

{
  "vendorVerified": true,
  "invoiceVerified": true,
  "paymentApproved": true,
  "sufficientFunds": true,
  "paymentAmount": 4500,
  "riskScore": 10
}

Response

200

application/json

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.

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.

trustRecordId · string · required

Unique Execution Trust Record identifier.

businessTransactionId · string · required

Business Transaction identifier.

transaction · Business Transaction · object · required

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.

Show child attributes

Example:

{
  "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 · Override · object[] · required

Override history. Append-only; empty on every transaction in this repository today (no route creates an Override).

Show child attributes

executions · Execution · object[] · required

Execution history. Append-only.

Show child attributes

verifications · Verification · object[] · required

Verification history. Append-only.

Show child attributes

receipts · Receipt · object[] · required

Receipt history. Append-only.

Show child attributes

trustRecordHash · string · required

Canonical hash of the Execution Trust Record, computed over its canonical serialized form.

signature · object · required

Cryptographic signature over the canonical Execution Trust Record, proving it was produced by Parmana and has not been modified since signing.

Show child attributes

createdAt · string<date-time> · required

UTC timestamp when the Execution Trust Record was first created.

updatedAt · string<date-time> · required

UTC timestamp when the Execution Trust Record was last extended with a new immutable artifact.