Version: v1

# Playbook API

Host, organize, search, and ship visual media over REST.

Playbook is a media library and a full digital asset manager (DAM).

**Base URL:** `https://api.playbook.com/v1`. Most endpoints are scoped to an organization (workspace) slug, for example `/v1/{org}/assets`.

### Authentication[​](#authentication "Direct link to Authentication")

Send a Bearer token in the `Authorization` header: `Authorization: Bearer YOUR_TOKEN`. Create and manage tokens yourself on the Developers tab in the Playbook app — there is no approval step. Tokens carry `read` and `write` scopes, enforced at the API layer, so a write call made with a read-only token returns `403`.

API access comes in two tiers. On Free and the Pro trial a token expires 30 days after it is created; on Pro, Pro Legacy, Team, the Team trial, Business and Enterprise tokens do not expire. A user can hold at most 10 active tokens at a time. Some plans carry no API access at all, in which case the Developers tab refuses to mint a token — that refusal is a `forbidden` error from the app, not an HTTP status on this API.

### Response envelope[​](#response-envelope "Direct link to Response envelope")

Successful responses wrap the payload in a top-level `data` key. List endpoints return `data` as an array and add a sibling `pagy` object carrying `current_page`, `page_items`, `total_pages` and `total_count`.

### Status codes[​](#status-codes "Direct link to Status codes")

`401` bad token, `403` missing scope or not permitted, `402` monthly quota exhausted, `404` not found, `406` required parameter missing, `422` validation failed, `429` rate limited (back off and retry), `5xx` server error.

### Request quota[​](#request-quota "Direct link to Request quota")

Every request to an organization-scoped endpoint (any path carrying a `{slug}`) counts against that organization's monthly request allowance, and each response carries the current state in `X-API-Quota-Limit`, `X-API-Quota-Remaining` and `X-API-Quota-Reset`. Requests that fail validation or authorization still count — a client burning its allowance on malformed requests is generating real load.

Once the allowance is spent, requests return **402** with the code `api_quota_exceeded` and a `Retry-After` header holding the seconds until the counter resets. 402 rather than 429: an exhausted monthly quota stays exhausted for days, and a client retrying a 429 with backoff would hammer the API for the rest of the period without ever succeeding. **Do not retry a 402.**

Pro and Team workspaces can lift the wall to a higher ceiling by enabling usage billing on the Developers tab, in which case requests beyond the included allowance are billed on the next invoice. See [Conventions](https://dev.playbook.com/docs/conventions#monthly-request-quota) for the per-plan numbers.

### Rate limit[​](#rate-limit "Direct link to Rate limit")

Separately from the monthly quota, requests are throttled per token at **120 requests per minute**, the same on every plan. Every API response carries the current window in `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window resets), so pace bulk work from those headers instead of guessing. Going over returns **429** with `Retry-After`; wait that many seconds and retry.

### Pagination[​](#pagination "Direct link to Pagination")

List endpoints accept `page` and `per_page` query parameters — except AI Search, which is cursor-paginated: pass `after_cursor` and follow `has_next_page`.

### Async ingest[​](#async-ingest "Direct link to Async ingest")

Uploads are asynchronous. Creating an asset returns a skeleton immediately; poll `GET /v1/{org}/assets/{token}` until `is_skeleton` is `false`.

### Build with AI[​](#build-with-ai "Direct link to Build with AI")

Every operation here is also available to AI assistants through the hosted [MCP server](https://dev.playbook.com/docs/guides/mcp), including the full asset version history covered in [Asset Versioning](https://dev.playbook.com/docs/guides/versioning). New to the API? Start with [Getting Started](https://dev.playbook.com/docs/getting_started).

## Authentication[​](#authentication "Direct link to Authentication")

* HTTP: Bearer Auth

| Security Scheme Type:      | http   |
| -------------------------- | ------ |
| HTTP Authorization Scheme: | bearer |