AI search
ai_searchAI-powered visual search for assets in a Playbook workspace. Understands what is depicted inside assets — colors, subjects, scenes, objects, and compositions. Use this when the user describes visual content: 'ocean waves in blue', 'product shots on white background', 'videos with people outdoors'. Works regardless of filename or tags. Prefer this over search_assets for any content-descriptive query. Scope it to a board with collection_token (plus nested_assets for a parent board) — unscoped it searches the whole workspace, which for a moodboard, pitch reel or client hand-off returns mostly assets from other projects. Also filters by uploader and by date range. 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 |
|---|---|---|---|
| query | Yes | Natural language search query | |
| 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. | |
| date_to | No | Inclusive upper bound, ISO 8601 date or datetime | |
| statuses | No | Restrict results to assets carrying these status or custom field VALUES, e.g. ['Approved']. Case-insensitive, and it covers the built-in Status and every custom field, exactly as in search_assets. Several values match ANY of them — unlike search_assets there is no `and` mode here. | |
| date_from | No | Inclusive lower bound, ISO 8601 date or datetime (e.g. '2026-08-13') | |
| parent_id | No | Search token returned as pagination.parent_id. Pass it alone to refine that search, or together with after_cursor to fetch its next page. | |
| date_field | No | Which date the range applies to. 'original' is when the file itself was created (EXIF date where available); 'uploaded' is when it was added to Playbook. Defaults to 'original', EXCEPT when `uploaded_by` is set, where it defaults to 'uploaded' — so 'what did Max upload last week' means what you expect. | |
| 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. | |
| after_cursor | No | Opaque cursor returned as pagination.after_cursor. Must be paired with parent_id from the same response. | |
| 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 — it is not part of what is searched. | |
| collection_token | No | Limit the search to a specific board |