BlackTwist REST API

Programmatic access to your BlackTwist account for scheduling, analytics, and management.

Postman CollectionDownload the ready-made collection with all endpoints pre-configured.

Use with Claude, ChatGPT & moreConnect any AI assistant to BlackTwist via our MCP server. No code required.

Base URL

https://blacktwist.app/api/v1/

Authentication

All API requests require authentication via an API key. You can pass the key using either of these headers:

Authorization: Bearer bt_api_...
# or
X-Api-Key: bt_api_...

See the Authentication page for details on creating and managing API keys.

Request Format

Send JSON bodies with Content-Type: application/json. All dates should be sent as local datetime strings without a timezone offset (e.g. 2025-03-15T09:00:00). They will be interpreted in your configured timezone from Settings. You may also send ISO 8601 dates with timezone info if you prefer explicit control.

Response Format

All responses return JSON. Successful responses include the requested data at the top level. Error responses use the following shape:

{
  "error": "A human-readable error message"
}

HTTP Status Codes

200 — Success
400 — Bad request (validation error)
401 — Unauthorized (missing or invalid API key)
403 — Forbidden (insufficient permissions or plan)
404 — Resource not found
429 — Rate limit exceeded
500 — Internal server error

Rate Limits

The API enforces two layers of rate limiting:

60 requests per minute per account — the main throttle. Creating additional API keys for the same account does not increase this limit.
300 requests per minute per IP address — a safety net across accounts sharing the same network.

If you exceed either limit you will receive a 429 Too Many Requests response. Wait and retry after a short delay.

Team Context

Many endpoints accept an optional teamId query parameter. When provided, the request operates in the context of that team. If omitted, the request uses your personal account context.

Postman Collection

Import our ready-made Postman collection to get started quickly with all endpoints pre-configured: Download Postman Collection

Authentication