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

# Execute API

> POST /api/execute — Run the X402 workflow (generate deliverables) after payment.

## Endpoint

```
POST /api/execute
Content-Type: application/json
```

***

## Request Format

| Field                  | Type   | Required | Description                                                                                                                 |
| :--------------------- | :----- | :------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `sessionId`            | string | Yes      | Workflow from Idea → Intent → Platform → Payment.                                                                           |
| `transactionSignature` | string | No       | Solana tx signature; if provided, it is verified before execution. For Dodo, usually omitted; webhook sets `dodoPaymentId`. |
| `platform`             | string | No       | Fallback if `context.selectedPlatform` is missing (e.g. after redirect).                                                    |

### Example (Solana)

```
{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactionSignature": "5VJ...abc"
}
```

### Example (Dodo)

```
{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

***

## Response Format

### Success (200)

| Field              | Type           | Description |
| :----------------- | :------------- | :---------- |
| `status`           | `"success"`    |             |
| `stage`            | `"execution"`  |             |
| `execution_result` | object         | See below.  |
| `next_stage`       | `"completion"` |             |

**execution\_result**

| Field                    | Type      | Description                                                                |
| :----------------------- | :-------- | :------------------------------------------------------------------------- |
| `agents_executed`        | string\[] | e.g. ProductManager, FrontendDev, BackendDev, DevOpsEngineer, ToolManager. |
| `deliverables`           | array     | `{ type, content, format, path?, agent? }` per file.                       |
| `total_cost_script`      | number    | Amount charged.                                                            |
| `execution_time_minutes` | number    | Rounded from seconds.                                                      |
| `review_passed`          | boolean   | From ReviewAgent; optional.                                                |
| `review_issues`          | string\[] | From ReviewAgent; optional.                                                |

### Example

```
{
  "status": "success",
  "stage": "execution",
  "execution_result": {
    "agents_executed": ["ProductManager", "FrontendDev", "BackendDev", "DevOpsEngineer", "ToolManager"],
    "deliverables": [
      { "type": "documentation", "content": "# PRD\n...", "format": "markdown", "path": "docs/PRD.md", "agent": "ProductManager" }
    ],
    "total_cost_script": 10000,
    "execution_time_minutes": 2,
    "review_passed": true,
    "review_issues": []
  },
  "next_stage": "completion"
}
```

### Error (4xx / 5xx)

| Field    | Description   |
| :------- | :------------ |
| `status` | `"error"`     |
| `stage`  | `"execution"` |
| `error`  | Message.      |

***

## Status Codes / Error Causes

| HTTP | Cause                                                                                                                                                                                          |
| :--- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `sessionId` missing; workflow context not found and recovery failed; `selectedPlatform` missing; `refinedRequirements` missing and no `idea` to build minimal; `transactionSignature` invalid. |
| 405  | Method not POST.                                                                                                                                                                               |
| 503  | One or more agents disabled via admin; `error` lists disabled agents.                                                                                                                          |
| 500  | `executeX402Workflow` (OpenRouter, platform-templates), `verifyTransaction`, or DB/Prisma error.                                                                                               |

***

## Implementation Notes

* **Context:** Uses `getWorkflowContextDB` then `getWorkflowContext`. If missing, can rebuild from `prisma.workflow` or create a minimal context when `platform` is provided. `platformOptions` and `refinedRequirements` are restored from DB/body/`idea` when possible.
* **Payment:** If `transactionSignature` is present, `verifyTransaction(transactionSignature)` in `lib/solana` is called; on failure, 400. For Dodo, execution proceeds when `dodoPaymentId` / `paymentMethod: 'dodo'` are set (by webhook).
* **Agents:** `agentsToExecute` comes from `platformOptions` for `selectedPlatform`, or defaults (e.g. ProductManager, FrontendDev, BackendDev; + DevOpsEngineer for Android/iOS). Each is checked with `isAgentEnabled(agentName)`; if any are disabled, 503.
* **Execution:** `executeX402Workflow(selectedPlatform, refinedRequirements, sessionId, agentsToExecute, workflowContext)` in `lib/openai` runs `generatePlatformDeliverables`, review, deduplication, etc. `workflowContext` includes `idea`, `analysis`, `answers`, `platformOptions`, `selectedPlatform`, `paymentDetails`, `supabaseIntegration`.
* **Side effects:** Updates `Workflow` with `executionResult` and `currentStage: 'execution'`; updates `AgentStat` per agent; creates `Transaction` and can update `User.totalSpent` for Solana payments.

***