Skip to main content
GET
/
pages
/
search
Search Pages
curl --request GET \
  --url https://api.buttercms.com/v2/pages/search/ \
  --header 'Authorization: <api-key>'
{
  "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"
          }
        ]
      }
    }
  ]
}
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.

Authorizations

​
Authorization
string
header
required

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.

Query Parameters

​
query
string
required

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

Maximum string length: 100
​
page_type
string

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

Maximum string length: 100
​
locale
string

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.

Maximum string length: 10
Example:

"en"

​
levels
integer
default:2

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 range: 1 <= x <= 5
​
page
integer
default:1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: x >= 1
​
page_size
integer
default:10

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Required range: 1 <= x <= 100
​
auth_token
string

Your ButterCMS read API token

Response

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.

Page search response using page-based pagination

​
meta
object
required
​
data
object[]
required

Array of pages matching the search query, sorted by relevancy