# REST API

Endpoint reference for the YouTube Translate HTTP API, including accounts, quotes, processing, and artifact reads.

Base URL: `https://api.youtubetranslate.com`. All JSON endpoints live under `/api`.

## Authentication

Two credential types are accepted:

| Method | Header | Use |
|---|---|---|
| API key | `X-API-Key: ytt_live_...` | Scripts and backends |
| OAuth | `Authorization: Bearer <token>` | MCP clients |

Account-owned credentials are required for work that spends credits. Reads against the demo need no credentials at all.

Every rate-limited response carries standard `RateLimit-*` headers. Limits are per key; see [Limits and retention](/docs/limits.md).

## Accounts

### `POST /api/accounts`

Creates an account and returns an API key exactly once.

```bash
curl -X POST https://api.youtubetranslate.com/api/accounts \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","accept_terms":true}'
```

```json
{
  "account_id": "account:96b9730e-a616-4392-a691-8c2629dd8f39",
  "api_key": "ytt_live_...",
  "warning": "Shown once. Store this credential securely."
}
```

`accept_terms` must be `true`, after reading `/terms` and `/privacy`. Registration is limited to five attempts per hour per address.

### `GET /api/account`

Returns the account ID and balance in microcredits.

```json
{
  "account_id": "account:96b9730e-...",
  "balance": { "available": 990000, "reserved": 0 },
  "paid_processing_enabled": true,
  "mode": "live"
}
```

`reserved` is the hold placed by in-flight jobs. It returns to `available` when the job settles.

## Quotes

### `POST /api/processing/quote`

Returns the cost ceiling for an operation without starting it.

```bash
curl -X POST https://api.youtubetranslate.com/api/processing/quote \
  -H "X-API-Key: $YTT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operation":"transcribe","url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","language":"en"}'
```

```json
{
  "mode": "live",
  "quote": {
    "operation": "transcribe",
    "internalId": "517acae2-4a13-4129-96f6-230fad1c7ffb",
    "artifactKey": "api/videos/517acae2-.../transcript.json",
    "maximumCreditUnits": 300000,
    "cached": false,
    "priceVersion": "2026-10-27-v1",
    "maxSourceSeconds": 1800
  },
  "balance": { "available": 990000, "reserved": 0 }
}
```

For `translate` and `summarize`, pass `video_id` instead of `url`. `cached: true` means the artifact already exists and the call is a cheap read.

## Processing

### `POST /api/videos`

Transcribes a public video.

| Field | Type | Required | Notes |
|---|---|---|---|
| `url` | string | yes | Public YouTube URL |
| `language` | string | no | Defaults to `en` |
| `max_credit_units` | integer | for uncached | At least the quoted maximum |

Cached video: `200` with the transcript inline.
New video: `202` with `job_id` and `status: "processing"`.
Missing budget: `428` with code `budget_required`, plus the quote.

```bash
curl -X POST https://api.youtubetranslate.com/api/videos \
  -H "X-API-Key: $YTT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-request-001' \
  -d '{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","language":"en","max_credit_units":300000}'
```

Send `Idempotency-Key` on any spending request you might retry. Reusing a key with a different payload returns `409`.

### `POST /api/videos/:id/translate`

| Field | Type | Required |
|---|---|---|
| `language` | string | yes |
| `max_credit_units` | integer | for uncached |

### `POST /api/videos/:id/summarize`

| Field | Type | Required |
|---|---|---|
| `language` | string | no |
| `length` | string | no, `short` `medium` `long` |
| `max_credit_units` | integer | for uncached |

### `POST /api/videos/:id/subtitles`

| Field | Type | Required |
|---|---|---|
| `language` | string | no |
| `format` | string | no, `srt` or `vtt` |
| `max_credit_units` | integer | for uncached |

### `POST /api/videos/:id/search`

| Field | Type | Required |
|---|---|---|
| `query` | string | yes |
| `language` | string | no |

### `GET /api/jobs/:id`

Returns job status: `processing`, `completed`, or `failed`.

## Reads

These never start provider work. They return `404` until the artifact exists.

| Endpoint | Returns |
|---|---|
| `GET /api/videos/:id` | Video metadata |
| `GET /api/videos/:id/transcript` | Transcript, optionally `?include_timestamps=true` |
| `GET /api/videos/:id/transcript/:language` | Transcript in a specific language |
| `GET /api/videos/:id/transcript/languages` | Languages available for this video |
| `GET /api/videos/:id/translations` | All retained translations |
| `GET /api/videos/:id/summary?language=en` | Summary |
| `GET /api/videos/:id/subtitles?language=en&format=srt` | SRT or VTT file |

## Demo

No credentials required, restricted to two allowlisted videos.

| Endpoint | Returns |
|---|---|
| `GET /api/demo/examples` | The demo video list |
| `GET /api/demo/transcript?url=...` | Transcript for a demo video |

## Billing

| Endpoint | Purpose |
|---|---|
| `POST /api/billing/checkouts` | Create a prepaid credit checkout (`{"pack":"starter"}`) |
| `GET /pay/:token` | Hosted Stripe Link payment page |
| `GET /pay/:token/status` | Whether the purchase settled |

### `POST /api/billing/checkouts`

Requires an account API key, not an OAuth token or the website session.

```json
{
  "checkout_url": "https://api.youtubetranslate.com/pay/...",
  "amount_cents": 100,
  "credit_units": 1000000,
  "mode": "live",
  "payment_method": "link"
}
```

Credit is granted only after Stripe confirms a settled Link payment. See [Pricing and credits](/docs/pricing.md).

## Service

| Endpoint | Purpose |
|---|---|
| `GET /api/health` | `200` when the API and database are healthy, `503` otherwise |
| `GET /llms.txt` | Agent brief |
| `GET /.well-known/oauth-authorization-server` | OAuth metadata |
