API Conventions

Behaviors that hold across every Playbook API endpoint. If you are building an integration, or an AI agent, against Playbook, treat this page as ground truth.

Base URL

All REST endpoints are served under:

https://api.playbook.com/v1

Most endpoints are scoped to an organization (workspace) slug, for example /v1/{org}/assets.

Authentication

Every request authenticates with a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Create and manage tokens yourself in the Playbook app, with no approval step. See Getting Started.

Scopes

Tokens carry scopes, enforced at the API layer:

• read lists and fetches boards, assets, comments, and search results.
• write creates, updates, moves, deletes, uploads, comments, shares, and publishes.

A write call made with a read-only token returns 403. Never ship a token in client-side code or paste it into a chat with an AI model. Configure it once as a request header.

Response envelope

Successful responses wrap the payload in a top-level data key:

{ "data": { "token": "abc123", "title": "Hero shot" } }

List endpoints return data as an array. Always read from data.

Status codes and errors

Code	Meaning
200	Success.
401	Authentication failed. Check your Bearer token.
403	Permission denied. Check the token's read / write scopes.
404	Not found. Check the organization slug, board token, or asset token.
406	Invalid input (used by batch URL ingest validation).
422	Validation error. The response body explains which field failed.
429	Rate limited. Back off and retry (see below).
5xx	Playbook API error. Retry with backoff.

Error responses include a human-readable message. Tokens are never echoed back in error bodies.

Rate limiting

The API may return 429 Too Many Requests under sustained load. Back off and retry after a short delay, using exponential backoff. Specific limits are not published, so design clients to tolerate 429 and 5xx responses gracefully.

Pagination

List endpoints accept page and per_page query parameters:

GET /v1/{org}/assets?page=2&per_page=50

Async ingest

Uploads are asynchronous. Creating an asset (from a URL, a batch of URLs, or a signed upload) returns immediately with a skeleton asset. The row exists, but the bytes are still being fetched and processed.

Poll GET /v1/{org}/assets/{token} until is_skeleton is false, then check:

• media_type populated means the asset processed successfully.
• source_error non-null means ingest failed (the message is the latest worker error).
• is_link: true means it was kept as a bare link (only when as_link: true was passed).

For batch URL ingest, pass a uuid per item to correlate each async result back to your request. See the Upload guide, Async Ingest Semantics for the full contract and recommended polling cadence.

Driving Playbook from an AI agent

Everything above is also available to AI assistants through the hosted MCP server, which exposes the same operations as tools, with the same scopes and the same async semantics, and can read these docs at runtime via read_documentation. See the MCP guide.