API Reference - Tornado API

Base URL

https://api.tornadoapi.io

Authentication

The customer endpoints below use the x-api-key header:

curl -H "x-api-key: sk_your_api_key" https://api.tornadoapi.io/usage

Job billing

Jobs are metered by data volume. Depending on your account, a full-source 720p billing floor can apply to clips, audio extraction and lower-resolution downloads. See Billing & Metering for the calculation, exemptions and worked examples.

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 queued or processing job
`POST`	`/jobs/{id}/retry`	Retry a failed, warning or client-cancelled 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
`GET`	`/spotify/show/{id}/hasVideo`	Inspect Spotify show video availability

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

The customer endpoints described here return JSON. Framework-level rejections and operational routes can use other response formats. Successful requests use 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 (job/bulk creation; other POST routes can return `200`)
`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 - Request rate, server capacity or an account quota reached; inspect the error and retry advice
`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 (retry advice can be in a header or JSON body, depending on the path)
`504`	Gateway Timeout - Long operation timed out

Rate Limits

The default allowance is 1,000 requests per second per authenticated client. Deployment and per-key configuration can override this value; read limit_requests_per_second in the rejection response. For direct access, all API keys in the same organization share one budget across API instances. Using another key in that organization, another connection or another IP address does not increase the allowance. A legacy key without an organization has its own budget. Marketplace requests are counted for the authenticated provider account, so tenants remain separate even when their integration uses a shared key. The API enforces the limit after authentication. A one-second window starts with the first admitted request; rejected requests do not extend it. If you reach the ceiling, the API responds with 429, Retry-After: 1, and a JSON error (example with the default limit):

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests for this authenticated client. Retry after 1 second. For multiple downloads with a direct API key, use POST /jobs/bulk with up to 100 jobs per request.",
  "retry_after": 1,
  "limit_requests_per_second": 1000,
  "bulk_endpoint": "/jobs/bulk",
  "max_jobs_per_bulk": 100
}

For multiple downloads, use POST /jobs/bulk with up to 100 jobs in one HTTP request. Wait for Retry-After before retrying a rejected request. Bulk requires a direct API key and shared encoding options. If the API cannot check the shared request allowance, it returns 503. Storage allowances, account quotas and server capacity checks are separate from the HTTP request ceiling. Their errors have their own explanation; grouping requests does not remove those limits. Poll job status every 2–5 seconds as a starting point and back off on throttling.

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

​Job billing

​Endpoints Overview

​Jobs

​Bulk

​Metadata

​Batch Operations

​User

​Response Format

​Success Response

​Error Response

​Status Codes

​Rate Limits

​OpenAPI Spec