Search Assets in User's Organization

Use the search endpoint to find assets across your entire Playbook organization by keywords, filters, and pagination.

Prerequisites

1. Access token: a Playbook API token with search permissions, sent as a Bearer token.
2. Organization Slug (slug): Identifier for your org (e.g., coolclient-ltd).

Endpoint & Authentication

Send your token in the Authorization header. (A token in the access_token query param also works, but avoid it — URLs leak into logs, browser history, and referrers.)

GET /v1/{slug}/search
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Required	Description
query	string	yes	Free-text search term (e.g., banner, logo).
page	integer	no	Page number (default: 1).
per_page	integer	no	Number of results per page (default: 20).
filters.media_type	string	no	Filter by media type (e.g., image/png).
filters.boards	array	no	Limit to assets sitting directly in one or more boards, by token.
filters.recursive_boards	array	no	Limit to one or more boards and everything nested under them. Mutually exclusive with filters.boards.
filters.title	string	no	Only items whose title contains this string.
filters.tags	array	no	Only items carrying these tags. Repeat the key: filters[tags][]=hero&filters[tags][]=summer.
filters.tags_op	string	no	How several tags combine: or (default) or and.
filters.statuses	array	no	Only items carrying these status or custom field values, e.g. filters[statuses][]=Approved. Case-insensitive, and it covers the built-in Status as well as every custom field.
filters.statuses_op	string	no	How several statuses combine: or (default) or and.
filters.uploaded_by	array	no	Only items uploaded by these people. Pass member tokens — see People and Uploaders. Repeat the key: filters[uploaded_by][]=asg_a&filters[uploaded_by][]=asg_b.

note

A person's name in query will not find their uploads — query searches the assets' own titles, tags and descriptions. Use filters[uploaded_by] with a member token instead. See People and Uploaders.

Scoping to a board

With no board filter, search covers the entire workspace — every board you can see. That is rarely what you want when working on one project, so pass a board token.

Which key you pass matters. filters[boards] matches an asset's own board, so a parent board whose assets all live in sub-boards matches nothing and the search comes back empty as though there were no such assets. filters[recursive_boards] matches the board and its whole subtree, and is the one to reach for whenever the token might be a parent.

curl --globoff "https://api.playbook.com/v1/coolclient-ltd/search?query=chair&filters[recursive_boards][]=client-delivery" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

Sending both keys returns 422: only one board clause can be applied, and choosing one for you would silently answer a different question. For a guaranteed-complete listing of everything under a board — rather than a relevance-ranked search — use GET /v1/{slug}/assets?collection_token=…&nested_assets=true, which reads the database directly instead of the search index. See Fetching Data.

Example Request

curl "https://api.playbook.com/v1/coolclient-ltd/search?query=banner&page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

With Filters

curl --globoff "https://api.playbook.com/v1/coolclient-ltd/search?query=&filters[media_type]=image/png&filters[boards][]=homepage-assets" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq

Example Response

{
  "data": [
    {
      "id": 200,
      "token": "hero-jpg",
      "title": "Hero Banner",
      "media_type": "image/jpeg",
      "display_url": "https://cdn.playbook.com/hero.jpg"
    },
    {
      "id": 201,
      "token": "logo-png",
      "title": "Logo PNG",
      "media_type": "image/png",
      "display_url": "https://cdn.playbook.com/logo.png"
    }
  ],
  "pagy": { "current_page": 1, "page_items": 2, "total_pages": 1, "total_count": 2 }
}

Error Handling

• 400 Bad Request: Missing query parameter.
• 401 Unauthorized: Invalid or missing token.
• 422 Unprocessable Entity: Invalid filter format.

Tips

• Use pagination to batch-load results in your UI.
• Combine filters to narrow down large datasets efficiently.