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.collection_token	string	no	Limit to a single collection.
filters.title	string	no	Only items whose title contains this string.

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 "https://api.playbook.com/v1/coolclient-ltd/search?query=&filters[media_type]=image/png&filters[collection_token]=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.