Playbook

View saved version →

---
name: build-app
description: Build and host a small web app over one Playbook board - a gallery, portfolio, catalogue, lookbook or viewer - with deploy_app, and update, list or delete apps already hosted. Use when the user wants a web page, site or app that shows their Playbook assets, or a link to one they can share.
---

# Build an app on a Playbook board

Playbook hosts small static web apps that show one board and its sub-boards at their own address. `deploy_app` is the only way to host one. Never put an HTML file on a board and share it through a permalink or a share link: those serve files, not pages, and the page will not run.

## Before writing any code

1. `read_documentation` with topic `hosted_apps`. It is the reference for the files an app may contain, the data calls it can make, the fields each asset row carries, and the starter app. Build from it, not from memory of the REST API: an app reads through its own relative `playbook/api/...` address with no key.
2. Agree on the board with the user, and on who may open the app. Whoever gets in sees the board and all its sub-boards, unapproved assets and uploader names included.
3. `list_apps` to see the workspace's apps. Deploying to a slug the workspace already uses replaces that app's files, and the workspace's plan caps how many apps it may have. If the user's board already has an app, ask whether to replace it or add another.

## Who may open the app

`deploy_app` takes `access`:

- `public`, the default for a new app: anyone with the address.
- `members`: people who can view the board in Playbook, after they sign in.
- `password`: visitors who give the `password` you pass with it, at least 8 characters, on plans with share-link passwords.

The board's own share settings do not protect the app; only its watermark and downloads apply to it (below). Ask the user which they want when the board is not meant for everyone. A redeploy without `access` keeps the app's access; the user can also change it under Developer in Playbook's settings.

## Uploads from visitors

An app can take files from its visitors into its own board, through `playbook/upload` as the `hosted_apps` topic shows. In an app that is not public, a signed-in visitor who may upload to the board can always upload. Anyone else can upload only while the board's share link allows uploads ("Allow uploads" or "Enable upload-only page" in the board's Share tab, a Pro feature). `share_board` with `enable_uploads: true` switches it on, but it also lets anyone with the board's share link upload, so ask the user first. Leave the link without a password, an email form or a past expiry: any of them refuses every upload from the app. `share_board` clears a password (`password: ""`) and an expiry (`expiration_date: ""`); an email form only the user can switch off, in the Share tab. Tell them that the app shows every visitor's files to every visitor.

## Watermark and downloads

An app follows the board's share link. When the link has a watermark, every image the app reads carries it, and the answers hold no clean address. When the link is on and allows downloads, visitors can download the original files through `playbook/download`, typing the link's password if it has one, like a PIN; the `hosted_apps` topic shows the call. For a gallery that shows watermarked previews and hands out originals behind a PIN, set both with `share_board` (`watermark_text`, `disable_downloads: false`, `password`), and ask the user first: the same settings apply to the share page itself. Turning a watermark on in the Share tab switches downloads off; switching downloads back on there, or `share_board` with `disable_downloads: false`, keeps both. Video is not watermarked.

For a PIN per event, share each event's sub-board with its own `password` and `disable_downloads: false`, and keep the app board's link on with `disable_downloads: true`: a sub-board link with a password sets the PIN and download terms for the files under it, the app boa

Preview of the first 4,000 characters. Read full instructions →

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.
- A hosted web app over a board, such as a gallery or catalogue: the `build-app` 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, archive and unarchive, 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 option fields, exact option names. Call `list_custom_fields` first and use the names it returns. A `multi_select` field takes a list (`["Web", "iOS"]`) and then holds exactly those options; every other field takes one value, and `""` or `[]` clears a field. A field or option the workspace does not have comes back as an error that lists the valid ones; that field keeps its previous value and the rest of the update is still saved. `create_custom_field` defines a new field (`field_type: "multi_select"` for one that holds several options), and called with the name of an existing option 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.
- `archive_assets` archives up to 1000 assets. Each leaves its group unless the group is archived with it, and a group left with one asset is dissolved. `unarchive_assets` moves archived assets to a board the user picks, since the original board is not remembered; find them with `search_assets` and `include_archived: true`, which searches every media type.
- `group_assets` stacks variants under a parent asset; `ungroup_assets` reverses it. Children move to the parent's board.

## Before a large change

Moving, archiving, 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, add a text watermark (`watermark_text`, with size, position, colour and opacity; an empty text removes it), and with `enable_uploads` let visitors drop files onto the board. A hosted app on the board follows the link's watermark and download settings.
- `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 an image in a document, on a website or in another tool. An asset's `display_url` is signed and expires, so it is only for looking at something now.

A permalink serves a file, not a web page: an HTML file behind one does not run. To host a page or app over a board, use the `build-app` skill.

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.