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

# API Reference

> Complete reference for the Tornado API

## Base URL

```
https://api.tornadoapi.io
```

## Authentication

All API endpoints require the `x-api-key` header:

```bash theme={null}
curl -H "x-api-key: sk_your_api_key" https://api.tornadoapi.io/usage
```

## Endpoints Overview

### Jobs

| Method   | Endpoint           | Description                      |
| -------- | ------------------ | -------------------------------- |
| `POST`   | `/jobs`            | Create a download job            |
| `GET`    | `/jobs/{id}`       | Get job status                   |
| `GET`    | `/jobs`            | List all jobs                    |
| `DELETE` | `/jobs/{id}`       | Cancel a pending job             |
| `POST`   | `/jobs/{id}/retry` | Retry a failed job               |
| `DELETE` | `/jobs/{id}/file`  | Delete a job's file from storage |

### Bulk

| Method | Endpoint     | Description                                     |
| ------ | ------------ | ----------------------------------------------- |
| `POST` | `/jobs/bulk` | Create multiple download jobs at once (max 100) |

### Metadata

| Method | Endpoint    | Description                                             |
| ------ | ----------- | ------------------------------------------------------- |
| `POST` | `/metadata` | Extract video metadata without downloading              |
| `POST` | `/is-short` | Detect whether a YouTube URL is a Short, video, or live |

### Batch Operations

| Method  | Endpoint            | Description                   |
| ------- | ------------------- | ----------------------------- |
| `GET`   | `/batch/{id}`       | Get batch status              |
| `PATCH` | `/batch/{id}/jobs`  | Rename jobs in a paused batch |
| `POST`  | `/batch/{id}/start` | Start a paused batch          |

### User

| Method   | Endpoint       | Description                                               |
| -------- | -------------- | --------------------------------------------------------- |
| `GET`    | `/usage`       | Get usage statistics                                      |
| `POST`   | `/user/s3`     | Configure S3-compatible storage (AWS S3, R2, MinIO, etc.) |
| `GET`    | `/user/s3`     | Get the current S3 storage configuration                  |
| `DELETE` | `/user/s3`     | Remove S3 storage configuration                           |
| `POST`   | `/user/blob`   | Configure Azure Blob Storage                              |
| `DELETE` | `/user/blob`   | Remove Azure Blob Storage configuration                   |
| `POST`   | `/user/gcs`    | Configure Google Cloud Storage                            |
| `DELETE` | `/user/gcs`    | Remove Google Cloud Storage configuration                 |
| `POST`   | `/user/gdrive` | Configure Google Drive delivery                           |
| `DELETE` | `/user/gdrive` | Remove Google Drive configuration                         |
| `POST`   | `/user/oss`    | Configure Alibaba Cloud OSS                               |
| `DELETE` | `/user/oss`    | Remove Alibaba OSS configuration                          |
| `POST`   | `/user/slack`  | Configure Slack failure notifications                     |
| `DELETE` | `/user/slack`  | Remove Slack webhook configuration                        |
| `POST`   | `/user/bucket` | Configure S3 storage (legacy, use `/user/s3` instead)     |
| `DELETE` | `/user/bucket` | Remove S3 storage (legacy)                                |

## Response Format

All responses are JSON. Successful responses have a `2xx` status code.

### Success Response

```json theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Error Response

```json theme={null}
{
  "error": "Invalid API Key"
}
```

## Status Codes

| Code  | Description                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------------------- |
| `200` | Success                                                                                                                 |
| `201` | Created (for POST requests)                                                                                             |
| `400` | Bad Request - Invalid parameters                                                                                        |
| `401` | Unauthorized - Invalid or missing API key                                                                               |
| `403` | Forbidden - Quota exceeded, IP not allowed, or feature not available on your plan                                       |
| `404` | Not Found - Resource doesn't exist                                                                                      |
| `429` | Too Many Requests - Server at capacity or rate cap reached (includes a `Retry-After` header)                            |
| `500` | Internal Server Error                                                                                                   |
| `502` | Bad Gateway - Transient upstream failure (e.g. `/is-short`)                                                             |
| `503` | Service Unavailable - Node draining, at capacity, or a storage backend is unavailable (includes a `Retry-After` header) |
| `504` | Gateway Timeout - Long operation timed out                                                                              |

## Rate Limits

Currently no strict rate limits. Recommended:

* Max 500 concurrent jobs
* Poll status every 2-5 seconds

## OpenAPI Spec

The raw OpenAPI specification is publicly available at:

```
https://api.tornadoapi.io/openapi.json
```

Use it to generate client SDKs or import the API into tools like Postman or Insomnia. The full human-readable documentation lives at [docs.tornadoapi.io](https://docs.tornadoapi.io) (the `/docs` path on the API host redirects there).