> ## Documentation Index > Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search Pages > Search for pages using a text query. Results are sorted by relevance and can be filtered by page type. Search for pages using a text query, returning a list of pages that match the search query sorted by relevancy. This endpoint provides flexible page discovery capabilities across your entire page structure. **Search Behavior**: Only the direct content of the Pages is searched. Any references that the Page might include are ignored during search, but references are still included in the response based on the `levels` parameter provided. Pages are returned sorted by relevancy to the search query. **Page Type Filtering**: You can optionally limit your search to a specific page type, or search only Single Pages using `*` as the page type parameter. **Empty Results**: If no results are found, the API returns an empty array: `"data": []` See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices. ## OpenAPI ````yaml /api/openapi/read_api.yaml get /pages/search/ openapi: 3.1.0 info: title: ButterCMS Read API version: 2.0.0 description: > Read endpoints for the ButterCMS API — Pages, Collections, Blog Posts, Blog Metadata, and Feeds. contact: email: support@buttercms.com license: name: ButterCMS Terms of Service url: https://buttercms.com/terms/ servers: - url: https://api.buttercms.com/v2 description: ButterCMS API v2 security: - readTokenAuthHeader: [] - readTokenAuthQuery: [] tags: - name: Pages description: > Retrieve pages from your ButterCMS account. **Single Pages**: Use `*` as the page_type to get Single Pages (those without a Page Type) which represent unique pages on your site like your Homepage. Useful for creating your sitemap.xml. **Page Type Pages**: Use the actual page type slug to get pages of that specific type. Page Types allow you to create many pages with the same structure. **Note:** The fields of a page are defined by you, they are customizable. Sample responses below contain a basic set of fields for illustrative purposes. - name: Collections description: > Retrieve collection items from your ButterCMS account. Collections are flexible, user-defined content structures with completely customizable field schemas. See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices. - name: Blog posts description: > Retrieve blog posts from your ButterCMS account. List blog posts with pagination and filtering options, or retrieve individual posts by slug. - name: Blog metadata description: > Retrieve blog-related metadata including authors, categories, and tags. These endpoints provide access to the organizational structure of your blog content. - name: Feeds and utilities description: > Generate XML feeds for content syndication and SEO. - **RSS Feed**: Fully generated RSS 2.0 feed for your blog - **Atom Feed**: Standards-compliant Atom 1.0 feed - **Sitemap**: XML sitemap for search engine discovery All feeds can be filtered by category or tag and include only published content from your organization. - name: Images - Info description: > ButterCMS has an integration with [Filestack](https://www.filestack.com/docs/api/processing/) for image transformations. You can leverage their robust set of image transformation capabilities. After you upload an image, to create a thumbnail, here's an example: - **Original URL**: `https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy` - **Thumbnail URL**: `https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy` For complete transformation options and parameters, see the [full Filestack documentation](https://www.filestack.com/docs/api/processing/). paths: /pages/search/: get: tags: - Pages summary: Search Pages description: > Search for pages using a text query, returning a list of pages that match the search query sorted by relevancy. This endpoint provides flexible page discovery capabilities across your entire page structure. **Search Behavior**: Only the direct content of the Pages is searched. Any references that the Page might include are ignored during search, but references are still included in the response based on the `levels` parameter provided. Pages are returned sorted by relevancy to the search query. **Page Type Filtering**: You can optionally limit your search to a specific page type, or search only Single Pages using `*` as the page type parameter. **Empty Results**: If no results are found, the API returns an empty array: `"data": []` See also: Architecture & Performance for guidance on `levels`, pagination, and performance best practices. operationId: searchPages parameters: - name: query in: query description: > The search query string to match against page content. Only the direct content of pages will be searched. References are excluded from search but will still appear in results. **Maximum Length**: 100 characters required: true schema: type: string maxLength: 100 examples: simple_search: value: buttercmsapi description: Simple keyword search phrase_search: value: frequently asked questions description: Multi-word phrase search - name: page_type in: query description: > The slug of the type of pages you want to limit your search to. - Use `*` if you want to search only Single Pages (without a Page Type) - Use a specific page type slug to limit search to that type - Omit this parameter to search across all page types **Maximum Length**: 100 characters required: false schema: type: string maxLength: 100 examples: single_pages: value: '*' description: Search only Single Pages specific_type: value: news description: Search only pages of type 'news' - $ref: '#/components/parameters/locale' - name: levels in: query description: > Depth of relationship serialization. Controls how many levels of referenced content to include: - **1**: Direct fields only, references as URIs - **2**: Direct fields + one level of references (default) - **3-5**: Deeper relationship traversal **Important**: Higher levels increase response size. Maximum 10MB per response. Valid range: 1-5 (inclusive). Values outside this range will be automatically capped. required: false schema: type: integer minimum: 1 maximum: 5 default: 2 examples: shallow: value: 1 description: Minimal depth (1 level) default: value: 2 description: Default depth (2 levels) deep: value: 5 description: Maximum depth (5 levels) - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/page_size' - $ref: 93cf2c7e-75ce-4beb-b455-38e9541bd339 - $ref: 86c8b313-f5c9-4a9e-9b7a-5b789f6e0aae - $ref: '#/components/parameters/auth_token' responses: '200': description: > **Success** Returns a hash with a `data` property that contains an array of pages matching the search query, and a `meta` property that contains pagination information. **Search Results**: Pages are returned sorted by relevancy. If no results are found, returns an empty array: `"data": []` **Content Searched**: Only direct page content is searched. References are excluded from search but included in response based on `levels` parameter. content: application/json: schema: oneOf: - $ref: '#/components/schemas/PageBasedPageSearchResponse' - $ref: '#/components/schemas/OffsetBasedPageSearchResponse' examples: search_results: summary: Search results found value: meta: previous_page: null next_page: null count: 2 data: - slug: example-news-page name: Example News Page page_type: news published: '2019-11-12T17:23:53.109696Z' updated: '2020-10-22T20:07:52.965850Z' fields: seo: title: Example News Page description: SEO Description keywords: SEO, Keywords headline: This is an example news page sections: - fields: headline: ... subheadline: ... call_to_action: ... type: hero - slug: example-news-page-2 name: Example News Page 2 page_type: news published: '2019-11-12T17:23:53.109696Z' updated: '2020-10-22T20:07:52.965850Z' fields: seo: title: Example News Page description: SEO Description keywords: SEO, Keywords headline: This is another news page sections: - fields: video_headline: ... video_link: ... type: product_video offset_search_results: summary: Offset-based pagination search results description: Using ?limit=10&offset=5 parameters value: meta: count: 15 next_offset: 15 previous_offset: null data: - slug: offset-news-page name: Offset News Page page_type: news published: '2019-11-15T17:23:53.109696Z' updated: '2020-10-25T20:07:52.965850Z' fields: seo: title: Offset News Page description: SEO Description for offset example keywords: SEO, Keywords, Offset headline: This is an offset-based search result sections: - fields: headline: Offset Section subheadline: Demonstrating offset pagination call_to_action: Learn More type: hero no_results: summary: No search results found value: meta: previous_page: null next_page: null count: 0 data: [] '400': description: | **Bad Request - Invalid Parameter** Invalid parameter value provided. This can happen when: - The `levels` parameter is not a valid integer between 1 and 5 - Invalid locale parameter provided - Missing required `query` parameter content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_query: summary: Missing required query parameter value: detail: Query parameter is required for search. invalid_levels: summary: Invalid levels parameter value: detail: >- levels query parameter should be an integer between 1 and 5 (inclusive) invalid_locale: summary: Invalid locale parameter value: detail: Invalid locale parameter invalid_locale_validation: summary: Locale not configured for organization value: detail: fr is not a valid locale '401': $ref: '#/components/responses/UnauthorizedResponse' '404': description: > **Not Found - Page Type Does Not Exist** The requested page type doesn't exist or you don't have access to it. This only applies when using the `page_type` parameter with a specific page type slug. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Not found. security: - readTokenAuthHeader: [] - readTokenAuthQuery: [] components: parameters: locale: name: locale in: query description: > Set to the api slug of your configured locale (e.g. `en` or `fr`). When omitted, this query parameter will default to your organization's default locale. required: false schema: type: string maxLength: 10 example: en examples: english: value: en description: English locale spanish: value: es description: Spanish locale french: value: fr description: French locale page: name: page in: query description: | Page number for page-based pagination. **Mutually exclusive with limit/offset parameters.** required: false schema: type: integer default: 1 minimum: 1 example: 2 page_size: name: page_size in: query description: | Number of items per page for page-based pagination. **Mutually exclusive with limit/offset parameters.** required: false schema: type: integer default: 10 minimum: 1 maximum: 100 example: 5 auth_token: name: auth_token in: query required: false schema: type: string description: | Your ButterCMS read API token example: your_api_token schemas: PageBasedPageSearchResponse: type: object description: Page search response using page-based pagination properties: meta: $ref: '#/components/schemas/PaginationMeta' data: type: array items: $ref: '#/components/schemas/PageObject' description: Array of pages matching the search query, sorted by relevancy required: - meta - data OffsetBasedPageSearchResponse: type: object description: Page search response using offset-based pagination properties: meta: $ref: '#/components/schemas/OffsetPaginationMeta' data: type: array items: $ref: '#/components/schemas/PageObject' description: Array of pages matching the search query, sorted by relevancy required: - meta - data ErrorResponse: type: object properties: detail: type: string description: Error message describing what went wrong example: Authentication credentials were not provided PaginationMeta: type: object properties: previous_page: type: - integer - 'null' description: Previous page number if it exists next_page: type: - integer - 'null' description: Next page number if it exists count: type: integer description: Total number of items PageObject: type: object description: A single page object that can be either a Single Page or Page Type page properties: slug: type: string description: Unique identifier example: example-news-page name: type: string description: Name of the Page example: Example News Page page_type: type: - string - 'null' description: >- API slug identifier of the page_type for the Page. null for Single Pages example: news published: type: - string - 'null' format: date-time description: Timestamp of when the page was first published example: '2019-11-12T17:23:53.109696Z' updated: type: string format: date-time description: Timestamp of when the page was most recently published example: '2020-10-22T20:07:52.965850Z' scheduled: type: - string - 'null' format: date-time description: >- Timestamp of when the page is scheduled to be published. If not scheduled, this field will be null example: null status: type: string enum: - published - draft - scheduled description: Status of the current version of the page example: published fields: type: object description: >- Contains all of the actual content for the Page - fields are customizable additionalProperties: true example: seo: title: Example News Page description: SEO Description keywords: SEO, Keywords headline: This is an example news page sections: - fields: headline: ... subheadline: ... call_to_action: ... type: hero OffsetPaginationMeta: type: object description: Pagination metadata for limit/offset pagination properties: count: type: integer description: Total number of items example: 25 next_offset: type: - integer - 'null' description: Offset for the next page, null if no next page example: 20 previous_offset: type: - integer - 'null' description: Offset for the previous page, null if no previous page example: null responses: UnauthorizedResponse: description: Unauthorized - Invalid or missing API token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Missing API token value: detail: Authentication credentials were not provided invalid_token: summary: Invalid API token value: detail: Invalid token securitySchemes: readTokenAuthHeader: type: apiKey in: header name: Authorization description: | Set the `Authorization` header to `Token your_read_api_token`. Example: `Authorization: Token abc123def456` Note: The header value includes the `Token` prefix. You can access your API token from your settings page. readTokenAuthQuery: type: apiKey in: query name: auth_token description: > Pass your API token via the `auth_token` parameter on every request: `?auth_token=your_read_api_token`. You can access your API token from your settings page. Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS. ````