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

# API Reference

> Complete reference for the VidJutsu Video Intelligence API

## Base URL

```
https://api.vidjutsu.ai
```

## Authentication

Most endpoints require an API key passed as a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.vidjutsu.ai/v1/accounts \
  -H "Authorization: Bearer vj_live_your_key_here"
```

Get your API key by [subscribing](/authentication) with any card via Stripe.

## Endpoints

### Intelligence

Each intelligence endpoint has its own daily rate-limit bucket. Buckets are independent.

| Method | Endpoint                | Description                       | Calls / day |
| ------ | ----------------------- | --------------------------------- | ----------- |
| POST   | `/v1/watch`             | AI watches video, freeform prompt | 50          |
| POST   | `/v1/extract`           | Pull frames, audio, metadata      | 100         |
| POST   | `/v1/transcribe`        | Speech-to-text with word timing   | 30          |
| POST   | `/v1/check`             | Validate spec against rules       | 100         |
| POST   | `/v1/compliance/video`  | Scan a video against platform TOS | 20          |
| POST   | `/v1/compliance/prompt` | Scan text against platform TOS    | 100         |
| POST   | `/v1/overlay`           | Burn text overlay onto a video    | 50          |
| GET    | `/v1/check/rules`       | Load per-client custom rules      | unmetered   |
| PUT    | `/v1/check/rules`       | Save per-client custom rules      | unmetered   |

### Storage

Storage endpoints are unmetered under your subscription.

| Method | Endpoint         | Description                              |
| ------ | ---------------- | ---------------------------------------- |
| POST   | `/v1/accounts`   | Create an account record                 |
| PUT    | `/v1/accounts`   | Update an account record                 |
| GET    | `/v1/accounts`   | List accounts (supports tag filtering)   |
| DELETE | `/v1/accounts`   | Delete an account                        |
| POST   | `/v1/posts`      | Create a post record (200/day)           |
| PUT    | `/v1/posts`      | Update a post record                     |
| GET    | `/v1/posts`      | List posts (supports tag filtering)      |
| DELETE | `/v1/posts`      | Delete a post                            |
| POST   | `/v1/upload`     | Upload media to CDN (100/day)            |
| POST   | `/v1/upload/url` | Upload from external URL                 |
| POST   | `/v1/references` | Create a reference record                |
| PUT    | `/v1/references` | Update a reference record                |
| GET    | `/v1/references` | List references (supports tag filtering) |
| DELETE | `/v1/references` | Delete a reference                       |
| POST   | `/v1/assets`     | Create an asset record                   |
| PUT    | `/v1/assets`     | Update an asset record                   |
| GET    | `/v1/assets`     | List assets (supports tag filtering)     |
| DELETE | `/v1/assets`     | Delete an asset                          |

### Billing & Keys

| Method | Endpoint               | Description                            |
| ------ | ---------------------- | -------------------------------------- |
| POST   | `/v1/subscribe`        | Start a subscription checkout session  |
| GET    | `/v1/credits/status`   | Poll checkout status, retrieve API key |
| GET    | `/v1/usage`            | Remaining daily capacity per endpoint  |
| GET    | `/v1/pricing`          | Current pricing + limits table         |
| POST   | `/v1/api_keys/rotate`  | Rotate your API key                    |
| POST   | `/v1/api_keys/recover` | Recover a lost API key                 |
| GET    | `/v1/info`             | API discovery + endpoint catalog       |

## Tags

Accounts and posts support AWS-style key-value tags for organization and filtering:

```json theme={null}
{
  "tags": [
    { "key": "brand", "value": "summer-launch" },
    { "key": "region", "value": "northeast" }
  ]
}
```

Filter on GET requests: `?tag.brand=summer-launch`

## Response codes

| Code  | Description                                                |
| ----- | ---------------------------------------------------------- |
| `200` | Success (read operations, edits)                           |
| `201` | Created (new records)                                      |
| `202` | Accepted (async operation started)                         |
| `400` | Missing or invalid parameters                              |
| `401` | Missing or invalid API key                                 |
| `403` | Subscription inactive or expired (`subscription_required`) |
| `429` | Daily rate limit reached                                   |

## Error format

All errors return a consistent JSON structure. On `429`, the response includes `retryAfter` (seconds until the bucket resets at 00:00 UTC):

```json theme={null}
{
  "error": "rate_limited",
  "message": "Daily limit reached for watch (50/day). Resets at midnight UTC.",
  "limit": 50,
  "retryAfter": 14523
}
```

## Synchronous responses

All intelligence endpoints return synchronous `200` responses with the result in the body. No polling required.

## CORS

The API allows cross-origin requests from any origin. Allowed headers: `Content-Type`, `Authorization`.

## Versioning

Responses include the `VidJutsu-Version` header indicating the current API version.