Playbook

Create a custom field on a workspace, or REPLACE the options of one that already exists. Matching is by name: if a select field with this name exists, its option list is overwritten and every option missing from `options` is deleted, taking that value off every asset holding it. Always pass the complete intended option set, and check list_custom_fields first when the field may already exist. The workspace's built-in 'Status' field cannot be replaced through this tool; use update_asset_status to assign its value to an asset. For a select field (the default) `options` cannot be empty. 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, and a name already used by a field of another type is refused. A NEW field is refused once the workspace reaches its plan's custom field quota — replacing the options of an existing field still works at the limit, so check list_custom_fields before assuming the workspace needs another field. A field's VALUE is set on an asset with update_asset's `fields` argument ({ "Priority": "High" }); there is no separate set-value tool. Field and option names are matched EXACTLY; update_asset answers an unknown one with an error naming the valid ones, and list_custom_fields has the spelling. Requires a `write`-scope token and workspace owner/admin permission.

create_custom_field

Add a note to a Playbook board — a sticky-note asset that holds text rather than a file. Use it to annotate a board: a brief, a caption, a to-do, context for the assets around it. Returns the finished note immediately (nothing is uploaded, so there is no polling step). Requires a token with the `write` scope. Tip: validate `collection_token` with get_board first — an unknown token silently falls back to an anonymous default board.

create_note

Step 1 of 2 for uploading a file you already HOLD — one generated locally, returned as base64 by an image API, or sitting on disk. Returns a one-time address to send the bytes to, plus the exact HTTP requests to make; the caller sends the bytes and finish_upload then turns them into an asset. Requires a token with the `write` scope and a caller that can make HTTP requests. Prefer upload_from_url whenever the file is already at a URL Playbook can fetch — that route is one call and needs nothing from you. Come here when it is not: no URL at all, a URL behind a login, an expired signed URL, a host that blocks datacenter addresses, or an ingest that failed with "Source URL too large to fetch; upload manually" (Playbook's fetcher runs to a five-minute streaming budget, which this path does not have — though it has a size ceiling of its own, below). When neither a reachable URL nor HTTP requests are available, share_board with enable_uploads returns a link a person can drop the file on. Files above 104857600 bytes are refused: these tools transfer in a single request, and splitting a larger file into chunks is what the Playbook web and desktop apps are for.

create_upload_url

Batch form of create_upload_url: request upload addresses for up to 100 files in one call, then send each file's bytes and finish them all with finish_uploads. Give every item a `uuid` of your own — it is echoed back beside that item's address, and with several similar files it is the only reliable way to tell which address belongs to which file. Returns a `batch_id` that finish_uploads needs: it holds a reservation against the workspace's quota until the batch completes — so prepare a batch only when you are ready to finish it, and pass the batch_id back. Use upload_from_urls instead when the files are already at URLs Playbook can fetch. If any single file cannot be handled the whole call is refused rather than half of it succeeding.

create_upload_urls

Soft-delete an asset. This is reversible from the Playbook trash for a limited time.

delete_asset

Delete a board and all of its contents. Destructive.

delete_board

Delete a custom field of any type, with all of its options. This strips the field's value from every asset that carried one, and is not reversible. The workspace's built-in 'Status' field is protected and cannot be deleted. Takes the field `token` from list_custom_fields, not its name. Requires a `write`-scope token and workspace owner/admin permission.

delete_custom_field

Remove an element from a board's published page and return the slot as it now stands. An id that is nowhere on the page succeeds with `converged: true`, which means nothing was removed. An id that exists but in a different slot than `slot_id` is a 404. Deleting a `section` removes its contents with it. Requires `modify` on the board and page-layout API writes enabled for the workspace — otherwise 403 `page_layout_api_disabled`, which only Playbook can turn on; retrying does not help. Concurrency: pass the `version_token` from get_page_layout as `expected_version_token`; if the page changed since, the call answers 409 `stale_document` and applies NOTHING — read again, re-decide, re-send. A successful write that sent a token returns the NEW `version_token`: send that on your next write, because your own write already made the old one stale. Of the 409s only `lock_wait_timeout` and `page_layout_library_locked` are safe to repeat unchanged. `converged: true` in the response means nothing changed (the goal state already held); `materialized: true` means the page had no stored document and this call saved the template's defaults. Both keys are ABSENT when false. The public page can keep showing the old version for up to an hour after a successful write, so a reload may not show the change.

delete_page_element

Edit the comment/note on an existing asset version, addressed by `version_number`. Requires a `write`-scope token and versioning enabled. Does NOT create a version and does NOT change the asset's bytes or head. Pass an empty string to clear the comment. Use `list_asset_versions` to find the `version_number`; an unknown or out-of-range number returns not found. Note the newest stored version is `head_version_number − 1` (head_version_number is the next, not-yet-assigned number).

edit_asset_version_comment

Step 2 of 2: turn bytes you have already sent to storage into a Playbook asset. Call it only after every step returned by create_upload_url has succeeded — this call does not transfer anything, it records what landed. Pass the `signed_gcs_id` from create_upload_url unchanged. If a step failed, do NOT call this; start over with a fresh create_upload_url.

finish_upload

Batch form of finish_upload: turn bytes already sent to storage into assets, all on the same board. Include only the items whose byte transfers actually succeeded. IMPORTANT — this call is NOT atomic: it creates the assets one at a time and does not roll back, so a failure partway through leaves the earlier ones created while the call reports an error. Never retry it after a failure; see the recovery steps in the error itself.

finish_uploads

Get full details of a specific asset by its token. For more than one asset use get_assets, which reads up to 100 in a single call — calling this in a loop is the slow way to read a board. This one always returns `ai_agent_payload`, where get_assets makes it opt-in. Returns metadata including approval state, title, media type, tags, statuses, description, URLs, and dimensions. Signed display URLs expire after about 24 hours; `permalink`, when present, does not expire. `colors` holds the image's primary colours as hex codes, most dominant first, so a board's palette can be built from its assets' `colors` without downloading the images. It is empty for anything with no rendered preview (notes, colour swatches, links), which means not analysed, not colourless. List and search results do not carry it; ask for an asset by token. A video's `stream_url` is null until an HLS encode has finished; reading never starts one — retry_video_processing does.

get_asset

Read the permanent public URL of one or more assets, optionally rendered at a size you choose. Reads only — it never publishes anything, so an asset that has no permalink yet is reported under `not_published`; run add_asset_permalinks on those first. An asset under `pending` is still being published: its URL is withheld until the file is in place, so read it again shortly instead of publishing it again. This is the URL to use anywhere the link has to outlive the session: a document, a deck, a web page, a hand-off to another system. For a throwaway image to look at right now, use get_asset_previews instead — it needs no permalink and costs no quota. `width`/`height` resize IMAGES only (one of the two keeps the aspect ratio); PDFs, video and everything else are served at their stored size and ignore both.

get_asset_permalinks

Render one or more assets as images at a size you choose, and get a URL per asset. This is how you LOOK at Playbook assets: the `display_url` on an asset is the full-size render (5000px is normal), which is wasteful to fetch and too large for most vision models. Ask for 1024 wide and you get a 1024px image. The URLs are SHORT-LIVED — they die at the end of the next hour, so 1-2 hours depending on when you call. They suit fetching now or showing in the current reply; anything that must keep working later — a stored link, a document, a hand-off — needs get_asset_permalinks. A SIZE IS REQUIRED — pass `width`, `height`, or both; without one this would hand back the same full-size render you already have. IMAGES ONLY: it renders the asset's original file, so a video or a PDF comes back with a URL that will not load, and an asset with no file at all (a note, a colour swatch, a link) is listed under `no_file_to_render` rather than given a URL. Check `media_type` starts with `image/` first. Tokens missing from the response entirely are under `not_found` — unknown, or not visible to this token. One render per token per call, so ask for the assets you actually need to see rather than a whole board.

get_asset_previews

Get full details for up to 100 assets in ONE call — the batch form of get_asset. Use it after list_assets or a search to read the fields those rows do not carry: description, `colors`, `source_url`, custom `fields`, dimensions and comment counts. Prefer it over calling get_asset in a loop; a 60-asset board is one call, not sixty. Tokens that do not exist, or that you cannot see, come back in `not_found` rather than failing the whole call — check it, because a missing asset is otherwise indistinguishable from one you forgot to ask for. Grouped child assets ARE returned here, unlike in list_assets, which lists only top-level rows.

get_assets

Get details of a specific board by its token. Returns the board's title, description, asset count, parent board, and child board count. `published_page` says whether the board's public page is live (`active`), its `url` (null unless live) and the `template` its page design uses (can be set on a page that is not live). `asset_count` covers the board AND every board nested under it (each group/stack counted once); list_assets on a board returns only assets sitting directly on it unless you pass `nested_assets: true`, so compare the count against that, not the plain listing.

get_board

List comments on an asset or board. Specify entity_type as 'asset' or 'board' and provide the token.

get_comments

Read an import run's progress: `status` (pending, active, completed, canceled), `cancel_reason`, `scanning` (still listing folders), the target `board_token` (files are in sub-boards named after each folder), and `files` counts (total, pending, completed, skipped, failed). `skipped` includes files already on the board unchanged. `cancel_reason` on `canceled`: `overlimit` — out of storage or assets, or the next file would have crossed into storage overage the workspace has not agreed to (nothing past that point was stored); `incomplete` — some files failed; `failed_to_start` — could not start, e.g. sustained provider rate limiting; `oauth_credential_deleted` / `target_collection_deleted` — the connection or board was removed; `blocked` — blocked by an admin. Poll no more than every 15–30 seconds.

get_import

The vocabulary for designing a board's published page — read it BEFORE publishing with a template or writing any page element. Returns: `templates` (the valid `template` ids for publish_board, each with its display name, default background/typography and the slots it mounts itself — a floor, not an inventory), `element_types` (the names of every element type), `enum_sets`, `background_colors` and `typographies` (the values update_page_settings accepts), `operations` (the argument map for apply_page_operations), and `limits`. The same for every workspace. The props of the element types are large (~40 KB together), so they come back only for the types named in the `element_types` argument, under `elements`: each type with the camelCase props it accepts, flagged `html`, `url`, `asset_token` or `dead` — a dead prop is stored but no longer rendered. A designed page is built from `section`s (up to 3 columns, each holding `note` and `asset` rows) under a `banner` hero, and its look comes from the `style` prop on notes and assets — gradients, cards, shadows, tilts, big type; read `style` on `note` before relying on `color`. There is no carousel or slideshow element: present a deck as ordered sections, or as a `grid` with `horizontalView` and `autoScroll`.

get_page_elements_catalog

Read the stored design of a board's published page: `template`, the page's own `background_color` and `typography` (null = inherited), `slots` (the page's regions and their elements), `subboards_settings` (one full second document per nested board shown on the page) and `version_token`. Returned verbatim — the ids and camelCase keys are exactly what the page element tools take back. `slots: null` is NORMAL for a page nobody has edited yet: it still renders its template's defaults. Address such a page by slot NAME (see `templates` in get_page_elements_catalog); the first write stores the defaults and returns real ids. 404 `page_layout_not_found` means the board has no page design — publish it with publish_board and a `template` first. Reads never change anything and are not gated by the page-layout write flag.

get_page_layout

Merge assets into a group. A group is a container asset that holds other assets as variants — different formats or crops of the same thing, or a set of colour swatches, which Playbook shows as a palette. The group has no file of its own and takes its preview from its first displayable child. Pass the asset the others should join as `parent_asset_token`; if it is already a group they are added to it, otherwise a new group is created around it. Children move to the parent's board. Requires a token with the `write` scope. Two rejections to plan around: every child must be ungrouped or already in this same group — one that belongs to a different group fails the whole call, so ungroup it first — and `parent_asset_token` must not itself be sitting inside a group. To add to an existing group, pass the GROUP's own token, not the token of one of its members.

group_assets

Import Dropbox folders into a board. Use this for files that live in the user's Dropbox, including private and team folders — upload_from_url cannot reach those. Google Drive and Dropbox are connected ONCE, by a person, in the Playbook web app — there is no tool that connects them. Connections belong to a Playbook user: this server only sees connections made by the same Playbook account it is signed in as. When list_import_sources has no source with the needed `provider`, its `connect_url` is where a person connects that service; the source is listed once they have. FOLDERS: pass the folder URL from the Dropbox address bar (https://www.dropbox.com/home/… on a personal account, /work/… for a team member), its path (/Clients/Acme), or an `id:` key. Shared links (dropbox.com/scl/…) are refused; the address-bar URL or the path is required. Every folder is checked against the connected Dropbox account first; one it cannot find is refused with the account's email. RE-SYNC: importing the same folder into the same `board_token` skips files already there unchanged (compared by Dropbox content hash), so a recurring sync should reuse the board. A file changed in Dropbox is added as a SECOND asset next to the old one, and renaming the Dropbox folder or its sub-board imports that folder again in full. Files that were first imported before this skipping shipped are downloaded again on every re-sync; the copies are usually merged away, but a workspace with duplicate merging turned off, or an asset kept in a group, ends up with real duplicates. Import into a new board to get skipping for them. WHERE FILES LAND: each folder becomes a sub-board NAMED AFTER THE FOLDER inside the target board, with its sub-folders nested below — not the target board itself. Find it with list_board_children on `board_token`, or list_assets with nested_assets. The import is ASYNCHRONOUS: this returns a run in `pending`; poll get_import until `status` is `completed` or `canceled`. Plans without unrestricted imports allow one active import per workspace; the refusal names the active import's token, so poll that instead of retrying. Storage overage cannot be agreed to here: the call is refused when the workspace has no storage left before overage it has not agreed to, and the import is canceled (`overlimit`) before storing a file that would cross it. A rate-limit error carries a retry delay — wait that long. Requires a `write`-scope token and workspace owner/admin permission.

import_from_dropbox

Import Google Drive folders into a board. Use this for files that live in the user's Google Drive, including private folders — upload_from_url cannot reach those. Google Drive and Dropbox are connected ONCE, by a person, in the Playbook web app — there is no tool that connects them. Connections belong to a Playbook user: this server only sees connections made by the same Playbook account it is signed in as. When list_import_sources has no source with the needed `provider`, its `connect_url` is where a person connects that service; the source is listed once they have. Every folder is checked against the connected Google account first; one it cannot see is refused with the account's email, which usually means the folder must be shared with that account. RE-SYNC: importing the same folder into the same `board_token` skips files already there unchanged, so a recurring sync should reuse the board. But a file changed in Drive is added as a SECOND asset next to the old one, and renaming the Drive folder or its sub-board imports that folder again in full. WHERE FILES LAND: each folder becomes a sub-board NAMED AFTER THE FOLDER inside the target board, with its sub-folders nested below — not the target board itself. Find it with list_board_children on `board_token`, or list_assets with nested_assets. The import is ASYNCHRONOUS: this returns a run in `pending`; poll get_import until `status` is `completed` or `canceled`. Plans without unrestricted imports allow one active import per workspace; the refusal names the active import's token, so poll that instead of retrying. Storage overage cannot be agreed to here: the call is refused when the workspace has no storage left before overage it has not agreed to, and the import is canceled (`overlimit`) before storing a file that would cross it. A rate-limit error carries a retry delay — wait that long. Requires a `write`-scope token and workspace owner/admin permission.

import_from_google_drive

The entry point for anything about an asset's earlier states — version history, previous or older versions, what changed and when, and picking one to restore or roll back to with revert_asset (annotate one with edit_asset_version_comment). Lists the version history of an asset, newest first. Each version has a `version_number` (the key to revert to or annotate), `md5` (content md5; may be a storage-placeholder value for async uploads), `size`, `media_type`, `source` (`UPLOAD` or `REVERT`), `comment`, `created_at`, `created_by_token`, a `revertable` flag, and `thumbnails`. Also returns `head_version_number` — the number the next version write will take (1 for a never-versioned asset). Reads are always available regardless of plan. On Free/Pro plans, versions older than the revert window are gated: `primary_gcs_id` is `null` and `thumbnails` is empty (the full-resolution original is not available on those plans). Use the live asset's `display_url` to preview current content.

list_asset_versions

List assets in a Playbook workspace, optionally filtered to a specific board. Set `nested_assets` with a board token to include its entire subtree. Use cursor pagination for a stable full crawl/reconcile; it is not a change feed and does not report deletions. For 'what is new in this board since X', pass `created_after` with `collection_token` and `nested_assets`. Signed display URLs expire after about 24 hours; store `permalink` when a permanent URL is required. Set `uploaded_by` to list everything one person added — prefer this over the search tools when you want a COMPLETE list, since it walks the database directly and is not subject to the search engine's result ceiling. Resolve the person with list_members first.

list_assets

List EVERY board nested under a given board — children, their children, and so on — in one paginated call, instead of walking list_board_children level by level. Each board carries its absolute `tree_depth`. `asset_count` covers the board AND every board nested under it (each group/stack counted once); list_assets on a board returns only assets sitting directly on it unless you pass `nested_assets: true`, so compare the count against that, not the plain listing.

list_board_descendants

List boards (collections) in a Playbook workspace. Supports title search via `query` and hierarchy depth control via `depth`, a string ('1' = top-level only, 'all' = full tree). Results are paginated — use `page` to navigate. `asset_count` covers the board AND every board nested under it (each group/stack counted once); list_assets on a board returns only assets sitting directly on it unless you pass `nested_assets: true`, so compare the count against that, not the plain listing.

list_boards

List the direct child boards of a given board. Use this to navigate the board hierarchy one level at a time — more efficient than `list_boards` with depth when you only need one node's immediate children. `asset_count` covers the board AND every board nested under it (each group/stack counted once); list_assets on a board returns only assets sitting directly on it unless you pass `nested_assets: true`, so compare the count against that, not the plain listing.

list_board_children

List a workspace's custom fields — the structured metadata vocabulary its assets use (Priority, Season, Usage Rights), each with its `field_type` and the options it allows. Call this FIRST before setting or filtering a field value: it is the only source of the exact field and option spelling. A field's VALUE is set on an asset with update_asset's `fields` argument ({ "Priority": "High" }); there is no separate set-value tool. Field and option names are matched EXACTLY; update_asset answers an unknown one with an error naming the valid ones, and list_custom_fields has the spelling. The list also contains the workspace's built-in 'Status' field, whose value is set with update_asset_status instead. A `select` field holds one of its options; a `date`, `person` or `url` field has no options and holds one free value per asset — see update_asset's `fields` parameter for the value formats. Returns every field in one call — this endpoint is not paginated.

list_custom_fields

List all available Playbook documentation topics. Returns a catalog of guides and references. Use the topic slug with read_documentation to read the full content.

list_documentation

List the storage accounts connected for import, each with its `provider` (`google_drive` or `dropbox`), the `token` import_from_google_drive / import_from_dropbox takes (use a source of the matching provider), and the account `email` it reads from (briefly null right after connecting). Google Drive and Dropbox are connected ONCE, by a person, in the Playbook web app — there is no tool that connects them. Connections belong to a Playbook user: this server only sees connections made by the same Playbook account it is signed in as. When list_import_sources has no source with the needed `provider`, its `connect_url` is where a person connects that service; the source is listed once they have. Requires workspace owner/admin permission.

list_import_sources

List the people in a Playbook workspace, or find one by name. Pass `query` to search by name or email — the match is fuzzy, so a partial or misspelled name works ('quackenbsh' finds 'Zephyrine Quackenbush'). Returns each member's `token`, which is the value the uploader filters on ai_search, search_assets, and list_assets require. Call this FIRST whenever a request names a person ('what did Max upload', 'files from Sarah') — a person's name typed into a search query does NOT match the person who uploaded an asset. A name can match several members; each comes back with its own token.

list_members

List all Playbook workspaces (organizations) the authenticated user belongs to. Returns each workspace's slug (used as identifier in other tools), name, and the user's role. `permalink_quota` reports how many permanent public URLs the plan still allows (`left` of `total`) — check it here before a large add_asset_permalinks call, since going over the cap refuses the entire batch.

list_organizations

Move one or more assets to a target board. Accepts an array of asset tokens and the destination board token. Requires a token with the `write` scope. The caller must have update permission on every source asset.

move_assets

Move an element to another position, another slot, or into/out of a `section` column on a board's published page. Returns both affected slots. A move that would change nothing converges. Requires `modify` on the board and page-layout API writes enabled for the workspace — otherwise 403 `page_layout_api_disabled`, which only Playbook can turn on; retrying does not help. Concurrency: pass the `version_token` from get_page_layout as `expected_version_token`; if the page changed since, the call answers 409 `stale_document` and applies NOTHING — read again, re-decide, re-send. A successful write that sent a token returns the NEW `version_token`: send that on your next write, because your own write already made the old one stale. Of the 409s only `lock_wait_timeout` and `page_layout_library_locked` are safe to repeat unchanged. `converged: true` in the response means nothing changed (the goal state already held); `materialized: true` means the page had no stored document and this call saved the template's defaults. Both keys are ABSENT when false. The public page can keep showing the old version for up to an hour after a successful write, so a reload may not show the change.

move_page_element

Create or update a board's public page, optionally changing its expiry, download restriction, or password. Returns the public URL. This is different from `share_board` — a published board is a standalone public landing page, while `share_board` returns an invite-style shareable link. Pass `template` to give the page a designed layout: valid ids are the keys of `templates` in get_page_elements_catalog (an unknown id is refused with the valid list). A template publish creates the page design that get_page_layout and the page element tools read and edit. Omit `template` on a board that is NOT live and has no page design yet, and it is published with `standard` so it is editable straight away (a workspace's own version of that template applies if it has one). A live page, or a board that already has a design, is never given a template implicitly. `template_applied` in the response names the template this call applied, and is absent when the design was left alone. An explicit `template` is refused with 409 `page_design_exists` when the page has stored element edits, rather than overwriting them: republish WITHOUT `template` to keep that design, and edit it with the page element tools. That refusal does NOT cover a design that is only page settings (background colour, typography set with update_page_settings) — a template publish replaces those. A page still following its template (never edited) switches to the new one. Exposure: this makes the board and its assets publicly accessible on the internet to anyone with the URL.

publish_board

Read a specific Playbook documentation page. Use list_documentation first to see available topics. Returns the text of a public Playbook developer-docs page (https://dev.playbook.com), including code examples and endpoints.

read_documentation

Revoke assets' permalinks, freeing the plan's permalink allowance. Destructive and NOT reversible in place: adding a permalink back mints a DIFFERENT URL, so anything embedding the old one stays broken. NOT an emergency takedown: the asset stops reporting a permalink at once, but the file already published stays fetchable to anyone holding the URL until the public copy is purged, which runs on a safety delay of about a week — so this call does not stop a leak that is already under way. Assets that have no permalink are skipped and are NOT in the response; if none of them has one the call is a 406. The response reports the freed-up `quota`. Requires `write` scope and update permission on every asset; one unknown token fails the whole call.

remove_asset_permalinks

Set the order of a slot's top-level elements on a board's published page. `ordered_ids` must be EXACTLY the slot's current top-level element ids — none missing, none repeated, none extra (ids nested in a section count as extra) — otherwise 422 `reorder_id_mismatch` names the offending ids and nothing changes. An order that already holds converges. To move one element, move_page_element is simpler. Requires `modify` on the board and page-layout API writes enabled for the workspace — otherwise 403 `page_layout_api_disabled`, which only Playbook can turn on; retrying does not help. Concurrency: pass the `version_token` from get_page_layout as `expected_version_token`; if the page changed since, the call answers 409 `stale_document` and applies NOTHING — read again, re-decide, re-send. A successful write that sent a token returns the NEW `version_token`: send that on your next write, because your own write already made the old one stale. Of the 409s only `lock_wait_timeout` and `page_layout_library_locked` are safe to repeat unchanged. `converged: true` in the response means nothing changed (the goal state already held); `materialized: true` means the page had no stored document and this call saved the template's defaults. Both keys are ABSENT when false. The public page can keep showing the old version for up to an hour after a successful write, so a reload may not show the change.

reorder_page_slot

Turn a share link of the user's workspace (`https://playbook.com/s/{workspace}/{link}`) into the board behind it. Returns `organization`, `board_token`, `board_title`, `uploads_enabled` and `expired`. To read what is on the link, call list_assets with THAT `organization` (a full URL names its own workspace, which may not be your default), `collection_token: board_token` and `nested_assets: true`. Only active links of a workspace the user belongs to resolve; a link that shares hand-picked assets rather than a board is refused.

resolve_share_link