# Search Assets in User's Organization

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

## Prerequisites[​](#prerequisites "Direct link to 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[​](#endpoint--authentication "Direct link to 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[​](#query-parameters "Direct link to 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](/docs/guides/people.md). 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](/docs/guides/people.md).

### Scoping to a board[​](#scoping-to-a-board "Direct link to 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](/docs/guides/fetching_data.md).

## Example Request[​](#example-request "Direct link to 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[​](#with-filters "Direct link to 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[​](#example-response "Direct link to 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[​](#error-handling "Direct link to Error Handling")

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

## Tips[​](#tips "Direct link to Tips")

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