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
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
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
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
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. 429 is reserved for
short-term throttling. A 429 includes Retry-After plus RateLimit-Limit,
RateLimit-Remaining and RateLimit-Reset; RateLimit-Reset is the number of seconds until
the short-term window resets. 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 for the per-plan numbers.
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
Uploads are asynchronous. Creating an asset returns a skeleton immediately; poll
GET /v1/{org}/assets/{token} until is_skeleton is false.
Build with AI
Every operation here is also available to AI assistants through the hosted MCP server, including the full asset version history covered in Asset Versioning. New to the API? Start with Getting Started.
Authentication
- HTTP: Bearer Auth
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |