# Playbook Developers

> Playbook is a media library and digital asset manager (DAM) with a hosted MCP server and a REST API built for AI agents. Connect an assistant in one step, no token to paste: point any MCP client at https://mcp.playbook.com/mcp and approve the browser sign-in — in Claude Code, `claude mcp add --transport http playbook https://mcp.playbook.com/mcp`. Everything an MCP agent can do is also available over the v1 REST API documented here, plus the playbook-sdk for embedding a media library. Start with the MCP guide below.


## Documentation


### Getting started

Start building with the Playbook API — the coder-friendly way to host, search, and ship your visual files. Authenticate, make your first call, and understand how organizations, boards, and assets fit together.

- [Getting Started](/docs/getting_started.md): Start building with the Playbook API — the coder-friendly way to host, search, and ship your visual files. Authenticate, make your first call, and understand how organizations, boards, and assets fit together.

### Examples

End-to-end examples for building real products on the Playbook API — portfolios, digital asset management, client galleries, brand portals, marketplaces, AI media pipelines, product and sales catalogs, and client presentation decks.

- [Examples](/docs/examples.md): End-to-end examples for building real products on the Playbook API — portfolios, digital asset management, client galleries, brand portals, marketplaces, AI media pipelines, product and sales catalogs, and client presentation decks.
- [AI media pipeline](/docs/examples/ai-pipeline.md): Build an AI media pipeline on the Playbook API — have agents search semantically, ingest generated variations in bulk, and auto-tag them, or skip code entirely with the hosted MCP server.
- [Brand portal](/docs/examples/brand-portal.md): Build a brand portal on the Playbook API — publish approved logos, fonts, and templates as an always-current, embeddable gallery with token-scoped access for partners.
- [Client gallery](/docs/examples/client-gallery.md): Build a client proofing gallery on the Playbook API — share a board of selects, collect feedback with comments, and deliver high-res downloads once the client approves.
- [Digital asset management](/docs/examples/digital-asset-management.md): Build a digital asset management (DAM) system on the Playbook API — define custom fields, ingest and tag assets, search by metadata, and keep downstream systems in sync with webhooks.
- [Creative marketplace](/docs/examples/marketplace.md): Build a creative marketplace on the Playbook API — accept seller uploads with signed URLs, power natural-language discovery with AI search, and deliver licensed originals on purchase.
- [Portfolio](/docs/examples/portfolio.md): Build an auto-updating portfolio on the Playbook API — create a board, add work, then publish it as a public web gallery or render your own with the board assets endpoint.
- [Client presentation deck](/docs/examples/presentation-deck.md): Build an interactive client presentation deck on the Playbook API — assemble slides on a board, share it as a full-screen click-through deck, and collect client feedback with comments.
- [Product catalog](/docs/examples/product-catalog.md): Build a product catalog on the Playbook API — organize product shots on boards with SKU, price, and category custom fields, then publish a browsable catalog or render your own storefront grid.
- [Sales catalog (interactive PDF)](/docs/examples/sales-catalog.md): Build an interactive sales catalog on the Playbook API — replace the static line-sheet PDF with a published, always-current board reps can browse, search, and download from.

### Guides

- [AI-Powered Search](/docs/guides/ai_search.md): Search Playbook assets with natural language using AI Search — semantic, concept-aware retrieval that goes beyond keyword matching.
- [Advanced Asset Management](/docs/guides/asset_management.md): Organize a portfolio or media library programmatically — the Playbook API patterns for moving, batching, tagging, and curating visual files at scale.
- [Comments and Collaboration](/docs/guides/comments.md): Read, post, and manage threaded comments on Playbook assets and boards via the API for collaboration and review workflows.
- [Create Boards in an Organization](/docs/guides/create_boards.md): Create new boards inside a Playbook organization via the API, including required permissions, parameters, and example requests.
- [Custom Fields](/docs/guides/custom_fields.md): Add structured metadata to Playbook assets with custom fields — define schemas, predefined options, and update values via the API.
- [Import from Dropbox](/docs/guides/dropbox_import.md): Import private and team Dropbox folders into Playbook boards from the API or MCP — connect once in the web app, start imports from folder URLs or paths, poll progress, and re-sync new files.
- [Fetching Data from the Playbook API](/docs/guides/fetching_data.md): Retrieve organizations, boards, and assets from Playbook with simple GET calls — authentication, pagination, and example responses.
- [Import from Google Drive](/docs/guides/google_drive_import.md): Import private Google Drive folders into Playbook boards from the API or MCP — connect once in the web app, start imports from folder URLs, poll progress, and re-sync new files.
- [Hosted Apps](/docs/guides/hosted_apps.md): Write a small public web app over one Playbook board — a gallery, a portfolio, a catalogue — and have Playbook host it. The app contract, a starter to copy, and how to deploy over MCP or the API.
- [Connect AI Assistants via MCP](/docs/guides/mcp.md): Connect Claude Code, Codex, Cursor, ChatGPT, and other MCP clients to Playbook so AI assistants can search, tag, upload, and manage your media via natural language. Browser sign-in, no token to paste.
- [Notes and Colors](/docs/guides/notes_and_colors.md): Create text assets in Playbook over REST or MCP — sticky notes with a background colour and card height, and colour swatches that merge into a palette.
- [People and Uploaders](/docs/guides/people.md): List workspace members, resolve a person's name to a token, and filter assets by who uploaded them.
- [Published Page Design](/docs/guides/published_page_design.md): Design a board's published Playbook page over the API or MCP — publish with a template, read the page layout, add, edit, move and delete elements, and set colours and typography safely alongside human editors.
- [Embed a Gallery with the SDK](/docs/guides/sdk.md): Embed a Playbook media gallery in your product with the playbook-sdk — install, give it a short-lived board token from your server, and customize columns, search, and events.
- [Search Assets in User's Organization](/docs/guides/search.md): Search Playbook assets across an organization by keyword, filters, and pagination using the v1 search endpoint.
- [Sharing and Publishing](/docs/guides/sharing_and_publishing.md): Share Playbook assets and boards privately with shared links, or publish boards as public web pages — full API reference and examples.
- [Uploading Assets to Playbook](/docs/guides/upload.md): Host your visual files in Playbook via API — upload from a public URL or via the two-step signed-upload flow, with endpoints, parameters, and complete examples.
- [Asset Versioning](/docs/guides/versioning.md): Track and restore previous versions of a Playbook asset — list version history, revert to an earlier version, upload new bytes as a new version, and annotate versions, over REST or MCP.
- [Webhooks](/docs/guides/webhooks.md): Receive real-time webhook notifications when Playbook assets are added, updated, or deleted — set up triggers, payloads, and verification.

### API reference

Full REST API reference for Playbook, the media library and digital asset management (DAM) platform. Endpoints for assets, boards, search, sharing, custom fields, and webhooks, with an interactive request explorer and code samples in curl, Python, Node, and Ruby.

- [Playbook API Reference](/docs/api.md): Full REST API reference for Playbook, the media library and digital asset management (DAM) platform. Endpoints for assets, boards, search, sharing, custom fields, and webhooks, with an interactive request explorer and code samples in curl, Python, Node, and Ruby.
- [Add Page Element](/docs/api/add-page-element.md): Inserts an element into a slot, or into a section column when `parent_element_id` is given.
- [AI Search](/docs/api/ai-search-organization-assets.md): AI powered search through current organization's assets
- [Apply Page Layout Operations](/docs/api/apply-page-layout-operations.md): Applies up to 50 `add` / `update` / `move` / `delete` / `reorder` operations **in order and
- [List Asset Children](/docs/api/asset-children.md): Get children for asset if it is a group
- [List Asset Comments](/docs/api/asset-comments.md): Asset comments
- [Read Asset Permalinks](/docs/api/asset-permalink-urls.md): Returns the permanent public URL of every requested asset that has one, optionally rendered at a given size. Read-only: it never publishes an asset, so an asset without a permalink comes back with a null one — call add_permalinks first. Unlike the short-lived URLs from /assets/transform, these do not expire. `width` and `height` apply to images only; every other media type is served at its stored size.
- [List Asset Versions](/docs/api/asset-versions.md): Lists an asset's immutable version history **newest-first** (paginated). The live asset row is
- [Read Many Assets](/docs/api/assets-batch-show.md): Full metadata for up to 100 assets in one request — the batch twin of GET /assets/{token}. Use it after a listing or a search to read the fields those rows do not carry (description, custom fields, size, source_url) without spending one request per asset. Tokens you cannot see, or that do not exist, come back in `not_found` instead of failing the call. Unlike the assets listing this addresses assets BY TOKEN, so a grouped child asset is returned when you ask for it.
- [Change Asset Tags](/docs/api/change-asset-tags.md): Updates asset tags
- [Check Organization Name](/docs/api/check-organization-name.md): Checks name availability for the new organization
- [List Board Assets](/docs/api/collection-assets.md): Get collection's assets
- [Copy Assets](/docs/api/copy-assets.md): Bulk copy assets to a different board (async operation)
- [Create Asset Permalinks](/docs/api/create-asset-permalinks.md): Creates permalinks for assets
- [Create Custom Field](/docs/api/create-custom-field.md): Creates a custom field. For a select field (the default) an existing field with the same name has its full option set replaced. For a date, person or url field pass field_type and no options; an existing field with the same name and type is returned unchanged.
- [Create Organization](/docs/api/create-organization.md): Creates new organization
- [Create Board Access Token](/docs/api/create-organization-board-access-token.md): Exchange your API token for a short-lived, read-only token limited to one board and its sub-boards. Call this from your own server and hand the result to code that runs in a browser, so your API token never leaves your server. The returned token can list and search that board through `GET /boards`, `GET /boards/{token}`, `GET /boards/{token}/children`, `GET /boards/{token}/assets`, `GET /assets`, `GET /search` and `GET /ai_search`, and can read one asset on that board through `GET /assets/{token}`; every other endpoint, and every write, answers 403 `board_scoped_token`. It expires after at most one hour and cannot create further tokens. Revoking your API token does not revoke tokens already created from it; they expire on their own. Each call counts as one API request and each token has its own rate limit, so reuse a token for a visitor's whole session rather than creating one per page view.
- [Create Webhook](/docs/api/create-trigger.md): Create a new webhook trigger.
- [Delete Asset Permalinks](/docs/api/delete-asset-permalinks.md): Deletes permalinks for assets
- [Delete Custom Field](/docs/api/delete-custom-field.md): Deletes a custom field: a select field with all its options, or a date, person or url field with the values assets held for it. The built-in Status field cannot be deleted.
- [Delete Page Element](/docs/api/delete-page-element.md): Removes an element and returns the slot as it now stands.
- [Delete Webhook](/docs/api/delete-trigger.md): Delete a webhook trigger.
- [Delete User](/docs/api/delete-user.md): Delete user
- [Download Asset](/docs/api/download-asset.md): The way to get an asset's original file: `raw_url` is a signed link (~24h) to the uploaded file, byte for byte, whereas `display_url`, `thumbnails` and image `permalink`s are re-encoded renders. Each call counts against the monthly quota, so fetch it when you need the file, not to display an image.
- [Download Shared Asset](/docs/api/download-shared-asset.md): Get download links for a shared asset
- [Get Import](/docs/api/get-import.md): Returns an import's status and file counts. Requires workspace owner or admin.
- [Get Organization](/docs/api/get-organization.md): Get info about one organization
- [Get Asset](/docs/api/get-organization-asset.md): Get info about one asset from organization
- [Get Board](/docs/api/get-organization-collection.md): Get info about one collection from organization
- [List Board Children](/docs/api/get-organization-collection-children.md): Get children of specific collection
- [List Board Comments](/docs/api/get-organization-collection-comments.md): Get collection comments
- [List Board Descendants](/docs/api/get-organization-collection-descendants.md): Get descendants of a specific board
- [Get User](/docs/api/get-user.md): Get info about one user
- [List User Favorites](/docs/api/get-user-favorites.md): Get info about user's favorites
- [List User Uploads](/docs/api/get-user-uploads.md): Get info about user's uploads
- [Group Assets](/docs/api/group-assets.md): Groups multiple assets together under a parent asset
- [List Import Sources](/docs/api/list-import-sources.md): Lists the Google Drive and Dropbox accounts the authenticated user connected in the Playbook web app; `provider` tells them apart. Connections are per user: an API token only sees connections made by its own user. When the provider you need is missing, send the user to `meta.connect_url` to connect it once, then call this again. Requires workspace owner or admin.
- [List Users](/docs/api/list-users.md): Get list of users
- [Get Current User](/docs/api/me.md): Get current user's info
- [Move Assets](/docs/api/move-assets.md): Bulk move assets to a different board
- [Move Page Element](/docs/api/move-page-element.md): Moves an element from one slot to another, or into/out of a section column, and returns
- [List My Organizations](/docs/api/my-organizations.md): Get current user's organizations
- [Batch Create Assets From URLs](/docs/api/organization-asset-batch-create-from-urls.md): Creates up to 100 assets at once by ingesting their bytes from public URLs.
- [Batch Complete Upload](/docs/api/organization-asset-batch-upload-complete.md): **Final Step of Batch Asset Upload Process**
- [Batch Prepare Upload](/docs/api/organization-asset-batch-upload-prepare.md): **Step 1 of Batch Asset Upload Process**
- [Transform Assets](/docs/api/organization-asset-transform.md): Transform image assets using arbitraty params
- [Complete Upload](/docs/api/organization-asset-upload-complete.md): **Final Step of Asset Upload Process**
- [Prepare Upload](/docs/api/organization-asset-upload-prepare.md): **Step 1 of Asset Upload Process**
- [List Assets](/docs/api/organization-assets.md): Get current organization's assets
- [List Boards](/docs/api/organization-collections.md): Get current organization's boards
- [Create Asset](/docs/api/organization-create-asset.md): Creates a single asset. Exactly one of `uri` or `text` is required, and which one you send
- [Create Board](/docs/api/organization-create-collection.md): Creating new board in current organization
- [Create Color Assets](/docs/api/organization-create-color-assets.md): Creates colour swatches — text assets that hold a colour rather than a file.
- [List Custom Fields](/docs/api/organization-custom-fields.md): Get current organization's custom fields. Every field carries a field_type: select fields list their options; date, person and url fields hold one free value per asset and have none.
- [Delete Asset](/docs/api/organization-delete-asset.md): Deletes an asset from the organization
- [Delete Board](/docs/api/organization-destroy-collection.md): Destroys collection in current organization
- [Update Asset](/docs/api/organization-update-asset.md): Updates asset attributes (PUT also would work)
- [Update Board](/docs/api/organization-update-collection.md): Update board in current organization. PUT request also will work
- [Read Published Page Layout](/docs/api/page-layout.md): Returns the **stored** design document for a board's published page: its `uuid`, the
- [Published Page Element Catalog](/docs/api/page-layout-elements.md): The whole published-page vocabulary, in one call. Read this **before** writing anything:
- [Playbook API](/docs/api/playbook-api.md): Host, organize, search, and ship visual media over REST.
- [Publish Board](/docs/api/publish-organization-collection.md): Publish a board to the web
- [Reorder Page Slot](/docs/api/reorder-page-slot.md): Replaces a slot's **top-level** element order.
- [Resolve Share Link](/docs/api/resolve-organization-shared-link.md): Resolve a share link of this workspace to the board behind it. `link_slug` is the last path segment of the share URL: for `https://playbook.com/s/{slug}/{link_slug}` pass `{link_slug}`. Then list the board's assets with `GET /v1/{slug}/assets?collection_token={board_token}&nested_assets=true` instead of reading the share page. Only links of the workspace in the path resolve, and only while they are active; a deactivated link, or one of a trashed board, is a 404.
- [Retry Video Processing](/docs/api/retry-asset-video-processing.md): The escape hatch for a video whose `stream_url` is stuck at null: starts an HLS encode unless one has already finished, whether the previous attempt failed, died on its way to the encoder or was never made. You do not need it for the normal path — on the plans that do not encode on upload (Free, Pro, Creative) simply reading the asset with GET /v1/{slug}/assets/{token} starts the encode, and `stream_url` fills in a few minutes later. Returns 422 when the encode has already finished and when the workspace cannot stream video at all. DO NOT POLL THIS ENDPOINT: it cannot tell a running encode from a dead one, so every call while one is under way queues a second job. To wait for a result, poll GET /v1/{slug}/assets/{token} and watch `stream_url`.
- [Revert Asset to a Version](/docs/api/revert-asset.md): Restores the asset head content to a prior stored `version_number` (delegates to the same
- [Search Assets](/docs/api/search-organization-assets.md): Search through current organization's assets
- [Set Asset Approval](/docs/api/set-asset-approval.md): Bulk approve or unapprove assets. Approval controls whether an asset is visible on shared and published pages. Requires workspace owner or admin.
- [Share Asset](/docs/api/share-organization-asset.md): Creates a Shared link with asset
- [Share Board](/docs/api/share-organization-collection.md): Create a Shared link for a board
- [Start Import](/docs/api/start-import.md): Imports Google Drive or Dropbox folders into a board; the provider is the one of the `source_token` connection. Each folder becomes a sub-board named after it inside the target board, with its sub-folders nested below. Asynchronous: poll Get Import until `status` is `completed` or `canceled`. Each folder is checked against the connected account before the import starts. Re-importing the same folder into the same board skips files already there unchanged (Dropbox files first imported before this skipping shipped are still downloaded again, and are only cleaned up by duplicate merging); a changed file is added next to the old one, and a renamed folder or sub-board is imported again in full. Plans without unrestricted imports allow one active import per workspace, and the refusal names the active import. Storage overage cannot be agreed to through the API: the request is refused when nothing is left before overage the workspace has not agreed to, and the import is canceled with `cancel_reason: overlimit` before storing a file that would cross that level. Returns 429 with `Retry-After` when the provider rate limits the connection, and 502 on other provider errors. Requires workspace owner or admin.
- [Track Downloads](/docs/api/track-download-on-organization.md): Tracks a download
- [Ungroup Assets](/docs/api/ungroup-assets.md): Removes assets from their groups, making them individual assets again.
- [Update Asset Status](/docs/api/update-asset-status.md): Updates asset status
- [Update Page Element](/docs/api/update-page-element.md): Replaces an element's content.
- [Update Published Page Settings](/docs/api/update-page-layout-settings.md): Changes the page's **own** design properties — its background colour and its typography.

### conventions

How the Playbook API behaves across every endpoint. Base URL, Bearer auth and scopes, the data response envelope, status codes, rate limiting, the monthly request quota and its headers, pagination, and async ingest. One ground-truth reference for developers and AI agents.

- [API Conventions](/docs/conventions.md): How the Playbook API behaves across every endpoint. Base URL, Bearer auth and scopes, the data response envelope, status codes, rate limiting, the monthly request quota and its headers, pagination, and async ingest. One ground-truth reference for developers and AI agents.

## Optional
- [Playbook product overview (llms.txt)](https://www.playbook.com/llms.txt): Product-level LLM index for playbook.com: pricing, use cases, and platform overview.