Create (execute) a Business Transaction
A second, independent entry point into the identical application.execute() pipeline as POST /execute. See packages/api/src/routes/transactions.ts. Constructs the Business Transaction identically to POST /execute: businessTransactionId must be a valid UUID (v1-v5) or the request fails before any persistence with a 400, and BusinessTransactionMapper.fromRequest rebuilds 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. The only behavioral difference from POST /execute is the success status code: 201, not 200. The response body shape is otherwise identical to POST /execute.
Authorizations
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
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.
Unique Business Transaction identifier. Must be a valid UUID on both POST /execute and POST /transactions (rejected with 400 otherwise).
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.
{
"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"
}Entity empowered to authorize execution within a trust domain. Immutable once issued.
{
"authorityId": "c0c01c23-04a2-45f2-a821-ef24bfca02d3",
"authorityType": "SERVICE",
"principalId": "ap-automation-svc",
"displayName": "Accounts Payable Automation",
"issuedAt": "2026-07-07T16:38:59.285Z"
}Immutable trust artifact proving that an Authority granted approval for an intended execution.
{
"authorizationId": "6e9d6aa6-6d20-40a8-b05d-383516365cc7",
"authorityId": "c0c01c23-04a2-45f2-a821-ef24bfca02d3",
"purpose": "Authorize vendor payment disbursement",
"issuedAt": "2026-07-07T16:38:59.285Z"
}Immutable declaration of the action an Authority intends to be executed under an Authorization.
{
"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"
}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).
{
"name": "vendor-payment",
"version": "2.0.0",
"schemaVersion": "1.0.0"
}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).
{
"vendorVerified": true,
"invoiceVerified": true,
"paymentApproved": true,
"sufficientFunds": true,
"paymentAmount": 4500,
"riskScore": 10
}Response
Execution Trust pipeline completed (see POST /execute, identical pipeline, different entry point and status code).
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.
Unique Execution Trust Record identifier.
Business Transaction identifier.
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.
{
"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 history. Append-only; empty on every transaction in this repository today (no route creates an Override).
Execution history. Append-only.
Verification history. Append-only.
Receipt history. Append-only.
Canonical hash of the Execution Trust Record, computed over its canonical serialized form.
Cryptographic signature over the canonical Execution Trust Record, proving it was produced by Parmana and has not been modified since signing.
UTC timestamp when the Execution Trust Record was first created.
UTC timestamp when the Execution Trust Record was last extended with a new immutable artifact.