Search assets
search_assetsSearch for assets in a Playbook workspace by metadata: filename, title, or tags. Use this when the user knows the name of an asset or is searching by tag or file type. Does NOT understand visual content — use ai_search for queries about what is depicted in the asset. Supports filtering by media type (image, video, document, audio), board, uploader, and status or custom field value. This is also the ONLY tool that finds assets BY a custom field value ('everything marked High') — pass the value as statuses, which ai_search also accepts. A filter-only call automatically searches all text (query: '*'), and any statuses call without an explicit media type searches every media type. To find what a PERSON uploaded, call list_members to resolve their name to a token, then pass that token as uploaded_by. Putting a person's name in query does NOT match the person who uploaded an asset — it searches the asset's own text and will return unrelated files.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed) | |
| query | No | Text search query. Omit it for a filter-only search such as `statuses` | |
| fields | No | Return ONLY these fields on each result. `token` is always included. Valid names: token, title, media_type, text_type, status, approved, approved_after, tags, permalink, display_url, stream_url, collection_token, size, is_skeleton, uploaded_by, source_error, ai_generated, ai_agent_payload. `display_url` and `permalink` are ~400 characters each, so narrowing a large result set is most of the saving. An unknown name is refused, not ignored: there is no `created_at`, `updated_at` or `type` among them — `media_type` is the name for an asset's kind, and its other metadata comes from get_asset or get_assets. | |
| statuses | No | Restrict results to assets carrying these status or custom field VALUES, e.g. ['High', 'Approved']. Case-insensitive, and it covers both the built-in Status and every custom field — get the exact option names from list_custom_fields. Matching is on the option name ALONE, with no way to say which field it came from, so a value name two fields share matches assets tagged under either. | |
| media_type | No | Filter by type. Ordinarily omitting this searches images only. When `statuses` is set, the tool automatically uses 'all' so no asset type is silently excluded. | |
| statuses_op | No | How to combine several `statuses`: 'or' (default) matches any of them, 'and' requires all of them at once — which is how you intersect values from different fields, e.g. Priority High AND Season Summer. Ignored unless `statuses` is set. | |
| uploaded_by | No | Restrict results to assets uploaded by these people. Pass member tokens from list_members. A name is accepted as a fallback and resolved server-side, but only when it matches exactly one member — otherwise the call fails and lists the candidates to choose from. | |
| organization | No | Workspace slug, as returned by list_organizations. Omit it when the account has a single workspace — it is then resolved from your token. Pass it only when the account has several, or when you mean a workspace other than the obvious one. | |
| nested_assets | No | Search the board's entire nested subtree rather than only the assets sitting directly in it. Requires `collection_token`. Set it whenever the token might be a PARENT board — without it a parent whose assets all live in sub-boards returns nothing at all. Caveat: subtree matching reads a search-index field that refreshes when an asset is re-indexed, so it can briefly lag a board being MOVED; list_assets with `nested_assets` reads the database and cannot. | |
| get_ai_payload | No | Include each result's `ai_agent_payload`. Default false, and the key is then ABSENT rather than null. This only RETURNS the payload — you cannot search or filter on its contents. | |
| collection_token | No | Limit search to a specific board |