Playbook

View saved version →

---
name: get-started
description: Orient in a Playbook workspace - list its workspaces and boards, look at what a board holds, and choose the right Playbook tool for a task. Use when the user has just connected Playbook, asks what they can do with it, or asks about their boards or assets without naming one.
---

# Get started with Playbook

Playbook is a digital asset manager. A workspace contains boards, and a board contains assets: images, video, documents, notes and colour swatches. Boards nest inside other boards.

## Find your bearings

1. `list_organizations` returns the workspaces the signed-in account belongs to. When there is only one, later calls can leave `organization` out.
2. `list_boards` returns boards, with a title search and a hierarchy depth. `list_board_children` and `list_board_descendants` walk one branch.
3. `list_assets` with a board token returns what that board holds. `get_asset` returns one asset in full.
4. `get_asset_previews` renders images at a size you choose, which is how to actually look at an asset.

Board and asset tokens belong to one workspace. Read them again from `list_boards` or `list_assets` in each session instead of reusing a token from an earlier one.

## Where to go next

- Finding, tagging, moving or grouping assets: the `organize-assets` skill.
- Adding files, notes, colours or a new version of a file: the `upload-files` skill.
- Share links, published pages and permanent URLs: the `share-and-publish` skill.
- Comments: `get_comments` and `create_comment`. People: `list_members`.
- Anything about the API itself: `list_documentation` and `read_documentation`.

## What Playbook cannot do here

- Hand over a file's bytes. A permalink or a `display_url` is the only way to reach a file.
- Read the text inside an image or extract captions from a video.
- Render a board as a PDF or a contact sheet.
- Turn a published-page or permalink URL back into a board or asset. Find the item by title instead. A board share link is the exception: `resolve_share_link` returns its board.

When a request needs one of these, say so and offer the nearest thing Playbook does provide.

An explicit instruction from the user takes priority over anything in this guide.

View saved version →

---
name: organize-assets
description: Find assets in Playbook and put them in order - search by keyword or by what an image shows, tag, set status and custom field values, move or copy between boards, and group variants. Use when the user wants to find, sort, label, clean up or restructure assets or boards in Playbook.
---

# Organize assets in Playbook

## Find the assets

- `search_assets` matches filename, title and tags, and filters by uploader, status and custom field value. Use it when the user gives words that appear on the asset.
- `ai_search` matches what an image shows or means, and filters by uploader and date range. Use it for a description such as "product shots on a white background".
- `list_assets` walks one board or a whole subtree when the user wants everything in a place rather than a match.

Look at candidates with `get_asset_previews` before acting on a visual judgement.

## Label them

- Tags on one asset: `change_asset_tags` adds and removes in one call.
- Title, description, tags, status, custom field values and board together: `update_asset`.
- The built-in Status field: `update_asset_status`.
- Approval and scheduled visibility for up to 1000 assets: `set_asset_approval`.

Custom fields have exact names and, for select fields, exact option names. Call `list_custom_fields` first and use the names it returns. A field or option the workspace does not have comes back as an error that lists the valid ones; the rest of that update is still saved. `create_custom_field` defines a new field, and called with the name of an existing select field it replaces that field's options, deleting any left out.

## Restructure

- `create_board` and `update_board` create, rename and re-parent boards.
- `move_assets` moves up to 1000 assets to a board in one call. `copy_assets` copies up to 1000 and finishes in the background.
- `group_assets` stacks variants under a parent asset; `ungroup_assets` reverses it. Children move to the parent's board.

## Before a large change

Moving, re-tagging or deleting many assets is hard to undo by hand. State which assets and boards will change and how many, and get the user's go-ahead before the call. `delete_asset` sends an asset to the trash, where it can be restored.

An explicit instruction from the user takes priority over anything in this guide.

View saved version →

---
name: share-and-publish
description: Share Playbook content outside the workspace - create a share link for a board or an asset, publish a board as a designed page, and mint permanent public URLs for files. Use when the user wants to send, share, publish, present or embed boards or assets from Playbook.
---

# Share and publish from Playbook

Each option below makes content reachable by people outside the workspace. Say what will become visible and to whom before making the call, and report the resulting URL together with its expiry or password.

## A link to a board or an asset

- `share_board` creates or updates a board's share link. It can set an expiry, restrict downloads, require a password, and with `enable_uploads` let visitors drop files onto the board.
- `share_asset` creates or returns the link for a single asset.
- `resolve_share_link` turns a board share link of the user's workspace back into its board.

## A published page

`publish_board` turns a board into a public page, with the same expiry, download and password controls. Pass a `template` to give it a design; the template ids come from `get_page_elements_catalog`.

To change the design afterwards:

1. `get_page_layout` reads the stored design and its `version_token`.
2. `add_page_element`, `update_page_element`, `move_page_element`, `delete_page_element` and `reorder_page_slot` change one thing each. `apply_page_operations` applies several in one call.
3. `update_page_settings` sets the page's background colour and typography.

`get_page_elements_catalog` lists the element types by name; pass `element_types` to get the props of the ones you need. `update_page_element` replaces the whole element, so send its full `props` back.

Pass the `version_token` as `expected_version_token` on each write and use the new token the write returns for the next one. The public page can keep showing the old version for up to an hour after a change.

Limits: a page whose elements have been edited cannot switch to a different template, and no tool unpublishes a page. Design editing is switched on per workspace by Playbook; where it is off the editing tools answer 403 `page_layout_api_disabled`, and retrying does not help.

## A permanent URL for a file

`add_asset_permalinks` publishes up to 200 assets at public URLs that do not expire. The number is capped by the workspace's plan, and `list_organizations` shows what is left. Files copy in the background, and ones still copying come back as `pending`. `get_asset_permalinks` reads the URLs later, and `remove_asset_permalinks` revokes them.

Use a permalink when a URL must keep working, for example in a document, a website or another tool. An asset's `display_url` is signed and expires, so it is only for looking at something now.

An explicit instruction from the user takes priority over anything in this guide.

View saved version →

---
name: upload-files
description: Add content to Playbook - upload a file from a URL or from bytes you hold, import folders from Google Drive or Dropbox, add notes and colour swatches, or store a new version of an existing asset. Use when the user wants to upload, import, save or add something to a Playbook board.
---

# Add files to Playbook

Pick the path by where the file is now.

## The file is at a URL Playbook can fetch

`upload_from_url` takes one public URL and a board. It returns a skeleton asset at once and Playbook fetches the file in the background, so read the asset back with `get_asset` before reporting the upload as finished. `upload_from_urls` takes up to 100 URLs for the same board. Playbook fetches anonymously: a link behind a login or an expired signed URL fails, and a very large or slow source runs out of time.

## You hold the file as bytes

A file generated locally, returned as base64 by another tool, or sitting on disk:

1. `create_upload_url` returns a one-time storage address and the exact request to make.
2. Send the bytes with that request. One request carries up to 100 MB.
3. `finish_upload` turns the stored bytes into an asset.

For several files use `create_upload_urls` and `finish_uploads`, and pass the `batch_id` from the first to the second. When a batch finishes only in part, the result says which files became assets; follow it instead of repeating the whole call, which would create duplicates.

## The file is in Google Drive or Dropbox

1. `list_import_sources` returns the connections the user has made, and a `connect_url`.
2. `import_from_google_drive` or `import_from_dropbox` takes 1 to 20 folders and a board.
3. `get_import` reports progress. Poll it until the status is `completed` or `canceled`.

A person connects Drive or Dropbox once in the Playbook web app. When no connection exists, give the user the `connect_url`.

## None of these is possible

`share_board` with `enable_uploads` returns a link where a person can drop files onto the board.

## Content that is not a file

- `create_note` adds a text note to a board.
- `create_colors` adds up to 100 colour swatches from hex codes or Pantone names; two or more become a palette.

## A new version of an existing asset

`create_asset_version` replaces an asset's file with one fetched from a public URL and keeps the previous file in its history. `list_asset_versions` shows the history, `revert_asset` restores an earlier version, and `edit_asset_version_comment` annotates one. Replacing a file changes what everyone sees, so confirm the target asset with the user first. Each call stores another version even for an identical file, so after a timeout check `list_asset_versions` instead of calling again. Large files are refused here and go through the Playbook web or desktop app.

## Files made by AI

The upload tools accept `ai_generated` and `ai_agent_payload`. Set `ai_generated` for content a model produced, and use the payload for the prompt or settings worth keeping with the asset.

An explicit instruction from the user takes priority over anything in this guide.