Skip to content
/
Update Page via Write API...

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

Create Page via Write API

Request

Create a new page using the ButterCMS Write API with support for multiple locales and automatic media uploads. This endpoint allows you to programmatically generate content that follows your predefined page type structure.

Page Type Requirement: The page type schema must already exist in your ButterCMS account before creating pages. Page types define the structure and field requirements for your content. You cannot create new Page Types through the API - they must be configured through the dashboard first.

Field Requirements: When creating a page, all field keys defined in your page type schema must be included in the request, even if they're marked as optional in your schema. For optional fields that you don't want to populate, provide empty strings (e.g., "hero_image": ""). This ensures your content structure remains consistent.

Locale Formats: Define all page content inside of a single fields object for accounts that do not have localization set up. For accounts with localization, all page content for each individual language should be defined inside of an object whose key is the locale slug. Nest these objects inside of the fields object. The locale codes must match those configured in your account.

Media Upload: If Media is the field_type for a chosen field, any URL can be provided as the field's value. The media corresponding to this URL will be automatically downloaded and uploaded to your ButterCMS media library. This ensures your media is hosted reliably and integrates with ButterCMS's CDN for optimal performance.

Publication & Scheduling: Pages are created as draft by default. You can set status=published to publish immediately. Scheduling future publication is not supported via the Write API.

Security
writeTokenAuth
Query
localestring

Set to the API slug of a pre-configured locale (e.g., 'en' or 'fr').

Usage: Only applicable when using the single-locale request format (WITHOUT Locales format). If you are using the single-locale format to create only a single locale's version of a page, you must specify the locale via this query param, e.g., ?locale=en.

Not applicable when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the fields object.

When omitted and using single-locale format, defaults to your organization's default locale.

Examples:

English locale

locale=en

Spanish locale

locale=es

French locale

locale=fr
Bodyapplication/jsonrequired

Page data in either single-locale or multi-locale format.

Request Body Formats:

  • WITHOUT Locales or Single Locale: If you don't have locales, or if you are only creating a single locale's version of a page, format your request body as a JSON object where fields is an object with each property representing a content field. Note: if creating only a single locale's version, you must specify the locale via query param, e.g., ?locale=en.
  • WITH Locales (Multi-Locale): The multi-locale format can be used to create one or more locales of a page at the same time. In this format, the fields object has an extra level and must be first mapped to the locale code. The locale codes must already be configured in your account; however, you can pick and choose which locales to create.
titlestringrequired

The title of the page.

Example: "Frequently Asked Questions"
slugstringrequired

The slug of the page.

Example: "faq"
statusstring

Status of the page. Can be 'draft' or 'published'. Defaults to 'draft'. Note that you cannot create a page with a status of 'scheduled' via the write API.

Default "draft"
Enum"draft""published"
Example: "draft"
page_typestringrequired

The key of the page type. The page type must already exist in your Butter account.

Example: "questions"
fieldsobjectrequired

Flexible Fields Object - Two Supported Formats

  • Format 1: Single-locale/direct fields

    • fields contains field names as keys (e.g., headline, questions).

  • Format 2: Multi-locale

    • fields contains locale codes as keys (e.g., en, es, fr).

  • Detection: The system automatically detects the format based on whether the top-level keys are locale codes or field names.

  • Field requirements

    • All field keys are required for each locale/format you include. If a field is not required in your page type, set it to an empty string.
    • Repeater fields must be JSON arrays of the repeater groups. For optional repeater fields, use an empty array ([]).
    • Providing a remote URL in any Media field triggers automatic download and upload to your ButterCMS media library.

  • Examples: See the Examples section for sample request bodies.

curl -i -X POST \
  'https://api.buttercms.com/v2/pages/?locale=en' \
  -H 'Authorization: Bearer <YOUR_Token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Frequently Asked Questions",
    "slug": "faq",
    "page_type": "questions",
    "status": "draft",
    "fields": {
      "headline": "Frequently Asked Questions",
      "hero_image": "",
      "body": "<p class=\"content\">We love questions</p>",
      "questions": [
        {
          "question": "Are dogs allowed?",
          "answer": "Leashed dogs are allowed.",
          "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
        },
        {
          "question": "Are wallabies allowed?",
          "answer": "Yes, leashed wallabies are allowed",
          "picture": "https://farm2.staticflickr.com/1840/29120307158_a9586a58b1_m_d.jpg"
        }
      ]
    }
  }'

Responses

Accepted - Page creation started successfully

The request has been accepted for processing. Full page creation occurs asynchronously, meaning the successfully created page may not show immediately. Pages are validated prior to returning this response, but it is possible that page creation may fail after returning a 202 response. If this happens, please contact support.

Bodyapplication/json
statusstring

Indicates that the page creation request has been accepted and is being processed asynchronously

Value"pending"
Example: "pending"
Response
application/json
{
  "status": "pending"
}

Update Page via Write API

Request

Update existing pages using PATCH requests with support for partial updates and multi-locale content. This endpoint provides flexible page modification capabilities while preserving unchanged content.

Page Type Flexibility: Use * to update pages across all page types when you know the slug but not the specific type, or specify the particular page type slug for optimized queries.

Partial Update Behavior: Include only the fields you want to modify in your request body. All other fields will retain their current values, making this ideal for targeted content updates without affecting the entire page structure. Note: PUT behaves like PATCH (partial update) for Pages. Use either method to perform partial updates.

Locale Handling: For single-locale updates, use the direct field format. For multi-locale organizations, nest your field changes under the appropriate locale codes. You can update specific locales without affecting others.

Status Control: Control page visibility by setting status to "draft" (keeps the page unpublished) or "published" (makes changes live immediately). Draft status is useful for staging content changes.

Immutable Fields: Page title and slug cannot be modified via PATCH requests to maintain URL consistency and prevent broken links. These core identifiers must remain stable after page creation.

Repeater Field Behavior: When updating repeater fields, you must include the complete array contents in your request. Partial repeater updates are not supported - the entire repeater will be replaced with your provided data.

Scheduling Limitation: Page scheduling is not available through the Write API. Any scheduled parameters in your request will be ignored, allowing you to safely update pages that are currently scheduled without affecting their publication timing.

Security
writeTokenAuth
Path
page_typestringrequired

The type of page to update.

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

Update page across all page types

*

Update page within news page type only

news
page_slugstringrequired

The slug of the page to update.

Example: faq
Query
localestring

Set to the API slug of a pre-configured locale (e.g., 'en' or 'fr').

Usage: Only applicable when using the single-locale request format (WITHOUT Locales format). If you are using the single-locale format to update only a single locale's version of a page, you can specify the locale via this query param, e.g., ?locale=en.

Not applicable when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the fields object.

When omitted and using single-locale format, updates the organization's default locale.

Examples:

English locale

locale=en

Spanish locale

locale=es

French locale

locale=fr
Bodyapplication/jsonrequired

Page update data in either single-locale or multi-locale format.

Partial Updates: Unlike creating pages, you only need to specify the fields you want to update. You don't need to include all fields.

Format Flexibility: The API accepts data wrapped in a top-level "data" key (Read API format). For example: {"data": {"status": "draft", "fields": {...}}} will be automatically unwrapped. You can use either title or name - both are accepted and name will be automatically converted to title.

Request Body Formats:

  • WITHOUT Locales or Single Locale: One format mirrors the read API response and can be used for pages without locales or updating a single, specified locale.
  • WITH Locales (Multi-Locale): The second format can be used for updating multiple locales at once. In this format, the fields object has an extra level and must be first mapped to the locale code to use.
titlestring

The title of the page. Note: This field cannot be updated via PATCH - it's included here for documentation completeness only.

Alternative: You can also use name which will be automatically converted to title.

statusstring

Status of the update. Can be 'draft' or 'published'. Defaults to 'draft'. Setting to 'published' will make your update live immediately.

Note: If scheduled timestamp or status is passed, these fields will be ignored to allow updating already scheduled pages.

Enum"draft""published"
Example: "draft"
fieldsobject

Flexible Fields Object - Two Supported Formats

  • Format 1: Single-locale/direct fields

    • fields contains field names as keys (e.g., headline, questions).

  • Format 2: Multi-locale

    • fields contains locale codes as keys (e.g., en, es, fr).

  • Detection: The system automatically detects the format based on whether the top-level keys are locale codes or field names.

  • Partial update behavior

    • Only specify the fields you want to update; omitted fields remain unchanged.
    • Repeater fields must be replaced in full; delta changes are not supported. If you need to clear a repeater, provide an empty array ([]).
    • Images and media can be updated by providing remote URLs.

  • Examples: See the Examples section below for sample request bodies.

curl -i -X PATCH \
  'https://api.buttercms.com/v2/pages/{page_type}/faq/?locale=en' \
  -H 'Authorization: Bearer <YOUR_Token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "draft",
    "fields": {
      "headline": "Frequently Asked Questions Updated",
      "questions": [
        {
          "question": "Are dogs allowed?",
          "answer": "Leashed dogs are allowed.",
          "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
        },
        {
          "question": "Another dog question",
          "answer": "Another dog answer",
          "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
        }
      ]
    }
  }'

Responses

Accepted - Page update started successfully

The request has been accepted for processing. Full page update occurs asynchronously, meaning the successfully updated page may not show changes immediately. Page updates are validated prior to returning this response, but it is possible that page update may fail after returning a 202 response. If this happens, please contact support.

Warning Messages: If you include fields that cannot be updated (like scheduled timestamp or scheduled status), the API will return warning messages explaining which fields were ignored.

Bodyapplication/json
statusstring

Indicates that the page update request has been accepted and is being processed asynchronously

Value"pending"
Example: "pending"
property name*stringadditional property

Warning messages for fields that were ignored during the update

Response
application/json
{
  "status": "pending"
}

Update Page via Write API (Full Update)

Request

Update existing pages using PUT requests. PUT behaves identically to PATCH (partial update), allowing you to update only the fields you specify while preserving unchanged content.

Page Type Flexibility: Use * to update pages across all page types when you know the slug but not the specific type, or specify the particular page type slug for optimized queries.

Partial Update Behavior: Include only the fields you want to modify in your request body. All other fields will retain their current values, making this ideal for targeted content updates without affecting the entire page structure.

Locale Handling: For single-locale updates, use the direct field format. For multi-locale organizations, nest your field changes under the appropriate locale codes. You can update specific locales without affecting others.

Status Control: Control page visibility by setting status to "draft" (keeps the page unpublished) or "published" (makes changes live immediately). Draft status is useful for staging content changes.

Immutable Fields: Page title and slug cannot be modified via PUT requests to maintain URL consistency and prevent broken links. These core identifiers must remain stable after page creation.

Repeater Field Behavior: When updating repeater fields, you must include the complete array contents in your request. Partial repeater updates are not supported - the entire repeater will be replaced with your provided data.

Scheduling Limitation: Page scheduling is not available through the Write API. Any scheduled parameters in your request will be ignored, allowing you to safely update pages that are currently scheduled without affecting their publication timing.

Security
writeTokenAuth
Path
page_typestringrequired

The type of page to update.

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

Update page across all page types

*

Update page within news page type only

news
page_slugstringrequired

The slug of the page to update.

Example: faq
Query
localestring

Set to the API slug of a pre-configured locale (e.g., 'en' or 'fr').

Usage: Only applicable when using the single-locale request format (WITHOUT Locales format). If you are using the single-locale format to update only a single locale's version of a page, you can specify the locale via this query param, e.g., ?locale=en.

Not applicable when using the multi-locale format (WITH Locales format), as locale codes are specified within the request body under the fields object.

When omitted and using single-locale format, updates the organization's default locale.

Examples:

English locale

locale=en

Spanish locale

locale=es

French locale

locale=fr
Bodyapplication/jsonrequired

Page update data in either single-locale or multi-locale format.

Partial Updates: You only need to specify the fields you want to update. You don't need to include all fields.

Format Flexibility: The API accepts data wrapped in a top-level "data" key (Read API format). For example: {"data": {"status": "draft", "fields": {...}}} will be automatically unwrapped. You can use either title or name - both are accepted and name will be automatically converted to title.

Request Body Formats:

  • WITHOUT Locales or Single Locale: One format mirrors the read API response and can be used for pages without locales or updating a single, specified locale.
  • WITH Locales (Multi-Locale): The second format can be used for updating multiple locales at once. In this format, the fields object has an extra level and must be first mapped to the locale code to use.
titlestring

The title of the page. Note: This field cannot be updated via PATCH - it's included here for documentation completeness only.

Alternative: You can also use name which will be automatically converted to title.

statusstring

Status of the update. Can be 'draft' or 'published'. Defaults to 'draft'. Setting to 'published' will make your update live immediately.

Note: If scheduled timestamp or status is passed, these fields will be ignored to allow updating already scheduled pages.

Enum"draft""published"
Example: "draft"
fieldsobject

Flexible Fields Object - Two Supported Formats

  • Format 1: Single-locale/direct fields

    • fields contains field names as keys (e.g., headline, questions).

  • Format 2: Multi-locale

    • fields contains locale codes as keys (e.g., en, es, fr).

  • Detection: The system automatically detects the format based on whether the top-level keys are locale codes or field names.

  • Partial update behavior

    • Only specify the fields you want to update; omitted fields remain unchanged.
    • Repeater fields must be replaced in full; delta changes are not supported. If you need to clear a repeater, provide an empty array ([]).
    • Images and media can be updated by providing remote URLs.

  • Examples: See the Examples section below for sample request bodies.

curl -i -X PUT \
  'https://api.buttercms.com/v2/pages/{page_type}/faq/?locale=en' \
  -H 'Authorization: Bearer <YOUR_Token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "draft",
    "fields": {
      "headline": "Frequently Asked Questions Updated",
      "questions": [
        {
          "question": "Are dogs allowed?",
          "answer": "Leashed dogs are allowed.",
          "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
        },
        {
          "question": "Another dog question",
          "answer": "Another dog answer",
          "picture": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
        }
      ]
    }
  }'

Responses

Accepted - Page update started successfully

The request has been accepted for processing. Full page update occurs asynchronously, meaning the successfully updated page may not show changes immediately. Page updates are validated prior to returning this response, but it is possible that page update may fail after returning a 202 response. If this happens, please contact support.

Warning Messages: If you include fields that cannot be updated (like scheduled timestamp or scheduled status), the API will return warning messages explaining which fields were ignored.

Bodyapplication/json
statusstring

Indicates that the page update request has been accepted and is being processed asynchronously

Value"pending"
Example: "pending"
property name*stringadditional property

Warning messages for fields that were ignored during the update

Response
application/json
{
  "status": "pending"
}

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

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.