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

# API Overview

> API structure, authentication, rate limiting, errors, and versioning.

## Workflow

| Endpoint        | Method | Role                                            |
| :-------------- | :----- | :---------------------------------------------- |
| `/api/idea`     | POST   | Submit idea → analysis and clarifying questions |
| `/api/intent`   | POST   | Submit answers → refined requirements           |
| `/api/platform` | POST   | Get platform options and recommendation         |
| `/api/payment`  | POST   | Validate Solana wallet/balance before payment   |
| `/api/execute`  | POST   | Run X402 execution after payment                |

***

## Payment (Dodo)

| Endpoint                    | Method | Role                                   |
| :-------------------------- | :----- | :------------------------------------- |
| `/api/dodo/create-checkout` | POST   | Create Dodo checkout session           |
| `/api/dodo/confirm-payment` | POST   | Confirm Dodo payment (optional)        |
| `/api/dodo/webhook`         | POST   | Dodo webhook (payment.succeeded, etc.) |

***

## Projects / GitHub

| Endpoint                                                   | Method   | Role                   |
| :--------------------------------------------------------- | :------- | :--------------------- |
| `/api/projects/download`                                   | GET      | Download project ZIP   |
| `/api/projects/generate`                                   | POST     | Trigger (re)generation |
| `/api/github/authorize`, `/callback`, `/upload`, `/status` | GET/POST | GitHub OAuth and push  |

***

## Admin

| Endpoint                   | Method | Role                  |
| :------------------------- | :----- | :-------------------- |
| `/api/admin/workflows`     | GET    | List workflows        |
| `/api/admin/agents`        | GET    | Agent stats           |
| `/api/admin/agent-control` | POST   | Enable/disable agents |
| `/api/admin/transactions`  | GET    | List transactions     |
| `/api/admin/users`         | GET    | List users            |
| `/api/admin/payments`      | GET    | Payments overview     |
| `/api/admin/treasury`      | GET    | Treasury/balance      |
| `/api/admin/files`         | GET    | Files/deliverables    |
| `/api/admin/download-file` | GET    | Download a file       |

***

## Other

| Endpoint                 | Method | Role                                         |
| :----------------------- | :----- | :------------------------------------------- |
| `/api/payment/config`    | GET    | Payment config (e.g. `UNIFIED_PRICE_SCRIPT`) |
| `/api/support/tickets`   | POST   | Create support ticket                        |
| `/api/user/register`     | POST   | Register user (e.g. by wallet)               |
| `/api/test/script-token` | GET    | Test SCRIPT token / wallet                   |
| `/api/test/a2a`          | GET    | Test A2A communication                       |

***

## Authentication

* **Workflow and payment:** No auth; the `sessionId` ties requests to a `Workflow`. For payment, the client sends `userWalletPubKey` (Solana) or completes Dodo checkout; the server validates balance or webhook.
* **Admin:** Handlers do **not** implement auth. In production you must add API keys, JWT, or role checks and protect `/api/admin/*` (and optionally Dodo webhook with `DODO_WEBHOOK_SECRET`).
* **GitHub:** OAuth via `/api/github/authorize` and `/api/github/callback`; `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `GITHUB_CALLBACK_URL`.

***

## Rate Limiting

* Not implemented in the codebase. For production, consider:
  * General: `upstash-rate-limit` or similar per IP / `sessionId`.
  * AI: limit concurrent `execute` and Idea/Intent/Platform to avoid OpenRouter quota issues.
  * Dodo webhook: optional throttling to avoid duplicate handling.

***

## Error Handling

### HTTP Status

| Code | Usage                                                                 |
| :--- | :-------------------------------------------------------------------- |
| 200  | Success (including payment `payment_issues` and some webhook acks)    |
| 400  | Bad request: missing/invalid body, missing context, invalid signature |
| 401  | Unauthorized (e.g. invalid Dodo webhook signature)                    |
| 405  | Method not allowed                                                    |
| 500  | Server/DB/AI error                                                    |
| 503  | Service unavailable (e.g. agents disabled in Execute)                 |

***

### Response Shape (Typical)

**Success**

```
{ "status": "success", "sessionId": "...", "stage": "...", ... }
```

**Error**

```
{ "status": "error", "stage": "...", "error": "Human-readable message" }
```

Some endpoints add `error` even when returning 200 (e.g. payment `payment_issues`).

***

## Versioning

* No URL or header versioning (e.g. `/v1/idea`). Changes are backwards-compatible where possible.
* To introduce versions: add a path prefix or `Accept`/`X-API-Version` and route to different handlers.