Skip to content
/
Get multiple Pages

ButterCMS API (2.0.0)

This OpenAPI specification covers the complete ButterCMS API, including read and write operations for Pages, Blog Posts, Collections, and more.

New Documentation Version

This is a new version of our API documentation built with OpenAPI standards. If you encounter any issues, inaccuracies, or have suggestions for improvement, please report them to support@buttercms.com.

The previous version of our documentation is still available at: https://buttercms.com/docs/previous-api/

API Overview

The ButterCMS API is organized around REST principles with predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including errors.

Our API provides comprehensive content management capabilities through both read and write operations. Content is served through a global CDN with 150+ edge locations, ensuring fast delivery worldwide.

The API supports creating, updating, and deleting items of three main content types:

Pages: Fully customizable, reusable schemas that are supercharged with features like structured local and global components, form integrations, and repeaters. These can be individually fetched via a slug and are ideal for complex web content requiring flexible layouts and advanced functionality.

Collections: Lighter-weight, customizable, reusable schemas for tables of data that are fetched via ID. Perfect for structured content like categories, team members, or product catalogs that primarily serve as reference data.

Blog Posts: Built-in content type from our blog engine, which comes out-of-the-box with categorization, tagging, predefined SEO, and authors. Designed for chronological content with standardized blog functionality.

Authentication is handled through token-based access; read operations can use a query parameter (auth_token) while write operations require header-based authentication for enhanced security.

Download OpenAPI description
index.json
index.yaml
Overview
E-mail

support@buttercms.com

License

ButterCMS Terms of Service

Languages
Servers
ButterCMS API v2

https://api.buttercms.com/v2/

Product Architecture & Integration

ButterCMS API architecture and performance characteristics for developers integrating headless CMS functionality.

Pages - Key Concepts

Essential concepts for working with ButterCMS Pages, including unique features, publication states, and architectural patterns.

Pages - Components

Complete guide to ButterCMS component system, exclusively available for Pages to create dynamic, structured layouts with reusable content blocks.

Important: Components are only available for Pages and are not supported by Collections or Blog Posts. This page-exclusive functionality enables sophisticated content architecture and flexible layouts that distinguish Pages from other content types.

Collections - Key Concepts

Essential concepts for working with ButterCMS Collections, including unique characteristics, publication workflows, and architectural patterns optimized for structured data management.

Blogs - Key Concepts

Essential concepts for working with ButterCMS Blog Posts, including predefined schemas, built-in organizational features, and publication characteristics.

Webhooks - Key Concepts

Complete Webhooks - Events system for real-time content change notifications.

ButterCMS sends HTTP POST notifications to your configured endpoints whenever content changes occur. This enables real-time synchronization, cache invalidation, automated workflows, and multi-channel content publishing.

Pages - Write

Create new pages using ButterCMS Write API. Programmatically create content to enable powerful use cases and scale your content faster.

Note: For Pages, PUT behaves like PATCH (partial update). Use either method to perform partial updates.

Operations

Pages - Read

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.

Operations

Get multiple Pages

Request

Retrieve a paginated list of pages for a given page type, or all Single Pages when using the wildcard * as the page type. This endpoint supports comprehensive filtering and sorting for Page Type collections.

Single Pages: Use * to retrieve Single Pages, which are unique pages like your Homepage, About page, or Contact page. This is particularly useful for generating sitemaps or building navigation structures that include your standalone pages.

Page Type Collections: Use the actual page type slug to retrieve all pages that follow the same structural template. This allows you to fetch collections like all news articles, product pages, or blog posts that share the same field schema.

Important: Advanced filtering and ordering capabilities are only available for Page Type endpoints, not when retrieving Single Pages with the * wildcard. Use dotted notation for field filters (e.g., fields.title=Home). See also: Architecture & Performance for guidance on levels, pagination, and performance best practices.

Security
readTokenAuth
Path
page_typestringrequired

The slug of the type of pages you want to retrieve, or * for Single Pages.

  • Use * to get Single Pages (those without a Page Type)
  • Use the actual page type slug to get pages of that specific type
Examples:

Get all Single Pages

*

Get pages of type 'news'

news

Get pages of type 'faq'

faq
Query
previewinteger

Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1. If you are trying to view a scheduled page for which the most recent page version is published, you must pass the preview parameter to see the scheduled changes.

Set to 1 to access unpublished/draft collection items. Useful for staging environments.

Default 0
Enum01
Example: preview=1
pageinteger>= 1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Default 1
Example: page=2
page_sizeinteger[ 1 .. 100 ]

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Default 10
Example: page_size=5
limitinteger[ 1 .. 100 ]

Maximum number of items to return for offset-based pagination.

Mutually exclusive with page/page_size parameters.

Default 10
Example: limit=5
offsetinteger>= 0

Number of items to skip before starting to return results.

Mutually exclusive with page/page_size parameters.

Default 0
Example: offset=10
localestring<= 10 characters

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.

Examples:

English locale

locale=en

Spanish locale

locale=es

French locale

locale=fr
levelsinteger[ 1 .. 5 ]

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.

Default 2
Examples:

Minimal depth (1 level)

levels=1

Default depth (2 levels)

levels=2

Maximum depth (5 levels)

levels=5
alt_media_textinteger

Media field response format.

Affects only media-typed fields. Other field types are unchanged.

  • 0 (default): Media fields return simple URL strings
  • 1: Media fields return objects with at least url and, when available, alt. If the stored media value is just a URL string, the object will include url only.
Default 0
Enum01
Examples:

Return media as URL strings (default)

alt_media_text=0

Return media as objects with at least url (alt included when available)

alt_media_text=1
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
orderstring

Can order by page level published, updated, or a content field of the Page Type. Defaults to ascending, prepend '-' to sort descending.

Note: Only available for Page Type endpoints, not for Single Pages (page_type=*).

Examples:

Order by title ascending

order=title

Order by published date descending

order=-published

Order by updated date ascending

order=updated
fields.seo.titlestring

Filter the result set by a nested field value. This is an example of field filtering — you can filter by any field using the pattern fields.<field_name>=<value>.

You can pass in multiple filters at once. For example: &fields.seo.title=Home&fields.headline=Welcome

To filter on Reference or Component fields use dot notation. For example: fields.hero.title=value or fields.hero.reference.title=value

Note: Field filtering is only available for Page Type endpoints, not for Single Pages (page_type=*).

Example: fields.seo.title=Home
fields.headlinestring

Filter the result set by a top-level field value. This is an example of field filtering — you can filter by any field using the pattern fields.<field_name>=<value>.

Note: Field filtering is only available for Page Type endpoints, not for Single Pages (page_type=*).

Example: fields.headline=Welcome
curl -i -X GET \
  'https://api.buttercms.com/v2/pages/{page_type}/?preview=1&page=2&page_size=5&limit=5&offset=10&locale=en&levels=2&alt_media_text=0&auth_token=your_api_token%2CYOUR_API_KEY_HERE&order=string&fields.seo.title=Home&fields.headline=Welcome'

Responses

Success

Returns a hash with a data property that contains an array of pages, and a meta property that contains pagination information.

  • For Single Pages (page_type=*): Returns pages without a page type
  • For Page Types: Returns pages of the specified type
Bodyapplication/json
One of:
metaobject(PaginationMeta)
dataArray of objects(SinglePage)
Response
application/json
{
  "meta": {
    "previous_page": null,
    "next_page": null,
    "count": 2
  },
  "data": [
    { … },
    { … }
  ]
}

Get a single Page

Request

Retrieve a specific page by its page type and slug. This endpoint is ideal for fetching individual pages for display on your website or application.

Page Type Flexibility: You can search across all page types using * as a wildcard, or optimize your query by providing a specific page type slug. Using the wildcard is useful when you know the page slug but aren't certain of its type, while specifying the page type can improve query performance. Use dotted notation for field filters (e.g., fields.title=Example). See also: Architecture & Performance for guidance on levels, pagination, and performance best practices.

Security
readTokenAuth
Path
page_typestringrequired

The type of page to retrieve.

  • Use * to search across all page types
  • Use a specific page type slug to limit search to that type
Examples:

Search across all page types

*

Search within news page type only

news
page_slugstringrequired

The slug of the page to retrieve.

Example: example-news-page
Query
previewinteger

Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1. If you are trying to view a scheduled page for which the most recent page version is published, you must pass the preview parameter to see the scheduled changes.

Set to 1 to access unpublished/draft collection items. Useful for staging environments.

Default 0
Enum01
Example: preview=1
localestring<= 10 characters

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.

Examples:

English locale

locale=en

Spanish locale

locale=es

French locale

locale=fr
levelsinteger[ 1 .. 5 ]

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.

Default 2
Examples:

Minimal depth (1 level)

levels=1

Default depth (2 levels)

levels=2

Maximum depth (5 levels)

levels=5
alt_media_textinteger

Media field response format.

Affects only media-typed fields. Other field types are unchanged.

  • 0 (default): Media fields return simple URL strings
  • 1: Media fields return objects with at least url and, when available, alt. If the stored media value is just a URL string, the object will include url only.
Default 0
Enum01
Examples:

Return media as URL strings (default)

alt_media_text=0

Return media as objects with at least url (alt included when available)

alt_media_text=1
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
curl -i -X GET \
  'https://api.buttercms.com/v2/pages/{page_type}/example-news-page/?preview=1&locale=en&levels=2&alt_media_text=0&auth_token=your_api_token%2CYOUR_API_KEY_HERE'

Responses

Success

A hash with a data property that contains the page matching the page slug.

Bodyapplication/json
dataobject(PageObject)

A single page object that can be either a Single Page or Page Type page

Response
application/json
{
  "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": { … }
  }
}

Search Pages

Request

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.

Security
readTokenAuth
Query
querystring<= 100 charactersrequired

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

Examples:

Simple keyword search

query=buttercmsapi

Multi-word phrase search

query=frequently asked questions
page_typestring<= 100 characters

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
  • If left empty, searching will not be limited to a specific Page Type

Maximum Length: 100 characters

Examples:

Search across all page types (default)

page_type=

Search only Single Pages

page_type=*

Search only pages of type 'news'

page_type=news
localestring<= 10 characters

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.

Examples:

English locale

locale=en

Spanish locale

locale=es

French locale

locale=fr
levelsinteger[ 1 .. 5 ]

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.

Default 2
Examples:

Minimal depth (1 level)

levels=1

Default depth (2 levels)

levels=2

Maximum depth (5 levels)

levels=5
pageinteger>= 1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Default 1
Example: page=2
page_sizeinteger[ 1 .. 100 ]

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Default 10
Example: page_size=5
limitinteger[ 1 .. 100 ]

Maximum number of items to return for offset-based pagination.

Mutually exclusive with page/page_size parameters.

Default 10
Example: limit=5
offsetinteger>= 0

Number of items to skip before starting to return results.

Mutually exclusive with page/page_size parameters.

Default 0
Example: offset=10
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
curl -i -X GET \
  'https://api.buttercms.com/v2/pages/search/?query=string&page_type=string&locale=en&levels=2&page=2&page_size=5&limit=5&offset=10&auth_token=your_api_token%2CYOUR_API_KEY_HERE'

Responses

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.

Bodyapplication/json
One of:

Page search response using page-based pagination

metaobject(PaginationMeta)required
meta.​previous_pageinteger or null

Previous page number if it exists

meta.​next_pageinteger or null

Next page number if it exists

meta.​countinteger

Total number of items

dataArray of objects(PageObject)required

Array of pages matching the search query, sorted by relevancy

data[].​slugstring

Unique identifier

Example: "example-news-page"
data[].​namestring

Name of the Page

Example: "Example News Page"
data[].​page_typestring or null

API slug identifier of the page_type for the Page. null for Single Pages

Example: "news"
data[].​publishedstring or null(date-time)

Timestamp of when the page was first published

Example: "2019-11-12T17:23:53.109696Z"
data[].​updatedstring(date-time)

Timestamp of when the page was most recently published

Example: "2020-10-22T20:07:52.965850Z"
data[].​scheduledstring or null(date-time)

Timestamp of when the page is scheduled to be published. If not scheduled, this field will be null

Example: null
data[].​statusstring

Status of the current version of the page

Enum"published""draft""scheduled"
Example: "published"
data[].​fieldsobject

Contains all of the actual content for the Page - fields are customizable

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"}]}
Response
application/json
{
  "meta": {
    "previous_page": null,
    "next_page": null,
    "count": 2
  },
  "data": [
    { … },
    { … }
  ]
}

Collections - Write

Create, update, and delete Collection items using ButterCMS Write API. Collections are user-defined content structures with completely customizable field schemas.

Operations

Collections - Read

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.

Operations

Blog Posts - Write

Create, update, and delete blog posts using ButterCMS Write API. Blog posts support rich content including HTML body, categories, tags, featured images, and SEO metadata.

Operations

Blog Posts - Read

Retrieve blog posts from your ButterCMS account. List blog posts with pagination and filtering options, or retrieve individual posts by slug.

Operations

Blog Metadata

Retrieve blog-related metadata including authors, categories, and tags. These endpoints provide access to the organizational structure of your blog content.

Operations

Webhooks - Events

Webhook event notifications sent by ButterCMS when content changes occur in your account.

ButterCMS automatically sends webhook notifications for various content events including blog posts, pages, and collection items. These events enable real-time integration with your applications, triggering immediate responses to content changes.

Event Types: Webhooks are triggered for create, update, publish, unpublish, and delete operations across all content types. Each event includes comprehensive payload data about the content that changed.

Delivery Method: All webhook events are delivered as HTTP POST requests to your configured endpoint URLs, with JSON payloads containing event metadata and complete content data.

Configuration: Webhook events are configured per content type in your ButterCMS account settings. You can select which events to receive and configure different endpoint URLs for different event types.

Webhooks

Feeds & Utilities

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.

Operations

Images - Info

ButterCMS has an integration with Filestack 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.