API Reference - Tornado API

Base URL

https://api.tornadoapi.io

Authentication

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

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

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error Response

{
  "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 (the /docs path on the API host redirects there).

​Base URL

​Authentication

​Endpoints Overview

​Jobs

​Bulk

​Metadata

​Batch Operations

​User

​Response Format

​Success Response

​Error Response

​Status Codes

​Rate Limits

​OpenAPI Spec