> ## Documentation Index
> Fetch the complete documentation index at: https://stir-vid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Control API

> FastAPI service that fronts StirVid generation and account state.

The Control API is a FastAPI service that lives at `services/api`. It is the single HTTP surface the web app and MCP server call.

## Endpoints

| Method | Path                           | Purpose                                                |
| ------ | ------------------------------ | ------------------------------------------------------ |
| `GET`  | `/health`                      | Liveness + upstream reachability.                      |
| `GET`  | `/v1/characters`               | List characters. Filters for public / platform-ready.  |
| `POST` | `/v1/projects`                 | Create a project (workspace for a set of jobs).        |
| `POST` | `/v1/projects/{id}/quote`      | Price a job. Returns cost in credits.                  |
| `POST` | `/v1/projects/{id}/jobs`       | Submit a job. Deducts credits and enqueues generation. |
| `GET`  | `/v1/projects/{id}/jobs`       | List jobs for a project, with status.                  |
| `GET`  | `/v1/account`                  | Current user, plan, credit balance.                    |
| `POST` | `/v1/characters/{id}/validate` | Run character eligibility check (platform-ready gate). |

## Auth

Production uses signed session tokens. Development supports a bypass header for local runs.

<Warning>
  `x-stirvid-user` is **dev-only**. It bypasses auth using a user id and must never be enabled in production. Guard it behind `NODE_ENV !== "production"`.
</Warning>

## Quote / job flow

```mermaid theme={null}
sequenceDiagram
  Client->>API: POST /v1/projects/{id}/quote
  API-->>Client: { credits, breakdown }
  Client->>API: POST /v1/projects/{id}/jobs
  API->>Billing: deduct(credits)
  Billing-->>API: ok
  API->>MotionEngine: submit
  MotionEngine-->>API: task_id
  API-->>Client: { job_id, task_id, status: queued }
```