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

# Execute

> POST /execute — run a Business Transaction through the Parmana Runtime

## Execute a Business Transaction

```
POST /execute
```

Implemented in `packages/api/src/routes/execute.ts`. The route validates `businessTransactionId`, then delegates to `application.execute(req.body)` — [`ExecutionTrustApplication.execute`](/docs/packages/runtime) in `packages/runtime/src/ExecutionTrustApplication.ts`.

<Note>
  A single call to `POST /execute` runs the entire pipeline synchronously: accept the [Business Transaction](/docs/concepts/business-transaction) → execute it through the [Runtime](/docs/architecture/runtime-architecture) → generate a [Verification](/docs/concepts/verification) → generate a [Receipt](/docs/concepts/receipt) → return the resulting [Execution Trust Record](/docs/concepts/execution-trust-record). See `ExecutionTrustApplication.execute` for the exact sequence.
</Note>

### Request body

The body is a full [`BusinessTransaction`](/docs/concepts/business-transaction):

```bash theme={null}
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{
    "businessTransactionId": "b6f1c8de-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "metadata": {
      "businessTransactionId": "b6f1c8de-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "correlationId": "b6f1c8de-1111-4c3d-8e9f-0a1b2c3d4e5f",
      "createdBy": "integration-test",
      "createdAt": "2026-07-01T00:00:00.000Z"
    },
    "authority": {
      "authorityId": "b6f1c8de-2222-4c3d-8e9f-0a1b2c3d4e5f",
      "authorityType": "USER",
      "principalId": "integration-test",
      "displayName": "Integration Test",
      "issuedAt": "2026-07-01T00:00:00.000Z"
    },
    "authorization": {
      "authorizationId": "b6f1c8de-3333-4c3d-8e9f-0a1b2c3d4e5f",
      "authorityId": "b6f1c8de-2222-4c3d-8e9f-0a1b2c3d4e5f",
      "purpose": "Integration Test",
      "authorizedAt": "2026-07-01T00:00:00.000Z"
    },
    "intent": {
      "intentId": "b6f1c8de-4444-4c3d-8e9f-0a1b2c3d4e5f",
      "authorizationId": "b6f1c8de-3333-4c3d-8e9f-0a1b2c3d4e5f",
      "action": "PAY_VENDOR",
      "resource": "BusinessTransaction",
      "issuedAt": "2026-07-01T00:00:00.000Z"
    },
    "policy": { "name": "vendor-payment", "version": "1.0.0" },
    "signals": { "amount": 1000, "vendorVerified": true, "paymentApproved": true },
    "status": "SUBMITTED",
    "createdAt": "2026-07-01T00:00:00.000Z"
  }'
```

<Warning>
  `businessTransactionId` must match a UUID (`/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i`, per the regex in `execute.ts`). Any other value — including the short IDs used in some examples throughout this documentation, like `txn-001` — is rejected with `400` before the request reaches the Runtime.
</Warning>

### Response `200`

The complete [`ExecutionTrustRecord`](/docs/concepts/execution-trust-record), including the appended execution, verification, and receipt.

### Response `400`

```json theme={null}
{ "error": "businessTransactionId must be a valid UUID." }
```

## SDK equivalents

<CodeGroup>
  ```ts TypeScript theme={null}
  const trustRecord = await client.execute(transaction);
  ```

  ```python Python theme={null}
  trust_record = client.execution.execute(transaction)
  ```
</CodeGroup>

See [`ExecutionApi`](/docs/typescript-sdk/apis) in the TypeScript SDK — note it also exposes `health()`, mapped to `GET /health`, alongside `execute()`.

## Related

<CardGroup cols={2}>
  <Card title="Execution" href="/docs/concepts/execution">The concept this endpoint produces.</Card>
  <Card title="Execution Lifecycle" href="/docs/runtime/execution-lifecycle">The full accept → execute → verify → receipt sequence.</Card>
  <Card title="Error Model" href="/docs/api/error-model">How failures during any stage of this pipeline are reported.</Card>
  <Card title="Basic Execution Guide" href="/docs/guides/basic-execution">A walkthrough of this endpoint end to end.</Card>
</CardGroup>