Skip to content
/
Reference Architecture

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.

Overview and Core Features

Pages serve as your primary content structure for individual web pages, articles, landing pages, or any content with a URL. Pages provide advanced functionality that distinguishes them from Collections and Blog Posts.

Unique Page Capabilities

  • Components: Structured content blocks including individual components and component picker fields for dynamic layouts
  • Repeaters: Fields that allow multiple instances of the same field structure
  • Form Integrations: Direct integration with third-party form services
  • Slug-based Retrieval: Human-readable URL identification system
  • True Versioning: Draft versions can be created over existing published content

Page Types

Pages can be structured as Single Pages (unique pages like Homepage) or Page Types (templated pages that share the same field structure). Page Types enable you to create multiple pages with consistent schemas while maintaining individual content.

Content Architecture

Pages excel at complex content scenarios requiring flexible layouts, dynamic components, and sophisticated reference relationships. They are ideal for marketing pages, product pages, articles, and any content requiring rich, structured presentation.

Content Publication States

Pages support a comprehensive three-state lifecycle that provides maximum flexibility for content management workflows.

  • Draft State: Content accessible only via preview mode, enabling content teams to review changes before publication. Draft pages can be created, edited, and previewed without affecting live content.
  • Published State: Content live and accessible via standard API endpoints, served through the global CDN with automatic caching and optimization.
  • Scheduled State: Content automatically published at specified times through dashboard configuration, enabling time-based content strategies and editorial calendar management.

Versioning Capability: Pages uniquely support creating new draft versions over existing published content, allowing continuous content iteration without taking existing pages offline. This enables sophisticated content workflows where multiple versions can be prepared and scheduled.

Previewing

Preview functionality enables content teams to review draft pages in full website context before publishing, providing confidence in content presentation and layout.

Pages Preview Workflow:

  1. Configure preview URLs for Page Types in your ButterCMS dashboard
  2. Content creators click "Preview" button and are redirected to your preview URL with preview=1 parameter
  3. Your application detects the parameter and includes it in ButterCMS API calls
  4. Draft page content is returned and displayed in complete website context
  5. Content teams can review layout, styling, and content presentation before publication

Technical Implementation: Preview mode works by appending preview=1 to API requests, which instructs ButterCMS to return the latest draft version rather than published content. This enables seamless integration with existing rendering systems.

Environment Strategy: Consider implementing environment-based configuration that automatically includes the preview parameter in development and staging environments, reducing manual parameter management across different deployment contexts.

Reference Architecture

Pages participate in ButterCMS's reference system, enabling complex content relationships and reusable data patterns that scale with your content needs.

Page-to-Page References

Reference fields pointing to other pages use page slugs as identifiers, providing human-readable and URL-friendly relationships that support navigation and content discovery patterns.

Implementation Examples

  • One-to-one relationships: "related_page": "example-page-slug" for featured content
  • One-to-many relationships: "related_pages": ["page-1-slug", "page-2-slug"] for content series
  • Navigational references: Supporting breadcrumbs, previous/next navigation, and content recommendations

Page-to-Collection References

Pages can reference Collection items to incorporate structured data like categories, team members, or product information, creating dynamic content that leverages centralized data management.

Reference Patterns

  • Category Assignment: "category": 123 using Collection item ID
  • Author Information: "authors": [456, 789] for multi-author content
  • Product References: "featured_products": [101, 102, 103] for e-commerce integration

Reference Management

Adding References

Provide appropriate identifiers (slug for pages, ID for collections) in Write API requests. References are validated during processing to ensure target content exists.

Removing References

Clear relationships using appropriate empty values:

  • Empty string (""): Removes one-to-one relationships
  • Empty array ([]): Removes one-to-many relationships
  • Null value (null): Removes either relationship type

Update Behavior

  • PATCH requests: Omitted reference fields remain unchanged, enabling selective updates
  • PUT requests: For Pages, PUT behaves like PATCH (partial update), allowing flexible field management

Reference Levels

The levels parameter controls reference field depth in API responses, balancing data completeness with response size and performance for optimal page loading.

Parameter Configuration

  • Default: levels=2 covers most page display scenarios
  • Range: 1-5 (values outside this range are automatically adjusted)
  • Level 1: Reference fields return API URIs only (minimal data transfer)
  • Level 2+: Reference fields return complete object data
  • Level 5 (max): Returns URIs for any remaining references beyond specified depth

Performance Guidelines for Pages

  • Use levels=1 for page listing or navigation menus where you need minimal data
  • Use levels=2 (default) for standard page display with basic reference information
  • Use levels=3-5 when displaying pages with complex nested reference chains
  • 10MB response limit: Reduce levels if responses approach this size limit

Response Examples

Level 1 Example (URIs only for faster loading):

{
  "data": {
    "fields": {
      "related_pages": ["/v2/pages/example-page-type/example-page-slug"],
      "category": ["/v2/content/?keys=categories[_id=1234]"]
    }
  }
}

Level 2+ Example (Complete objects for rich display):

{
  "data": {
    "fields": {
      "related_pages": [
        {
          "slug": "example-page-slug",
          "fields": {"title": "Example Page", "summary": "..."}
        }
      ],
      "category": [
        {"meta": {"id": 1234}, "name": "Technology", "description": "..."}
      ]
    }
  }
}

Advanced Features

Localization

Multi-language support enables Pages to serve international audiences with locale-specific content while maintaining consistent schemas and reference relationships.

Account Configuration

Locale support must be configured in your ButterCMS account settings before creating multi-language pages. Each locale is identified by an API slug (such as en, es, fr) that you define during setup.

Important: Once locales are added to an account, they cannot be removed. Plan your internationalization strategy carefully before configuration.

Content Versions

Pages can maintain separate content versions for each configured locale, allowing the same page structure to serve different language markets while preserving field schemas and component layouts.

API Integration:

  • Specify locale: Add locale=en parameter to retrieve pages in specific language
  • Default locale: Omit parameter to receive content in your organization's default locale
  • Write API: Create localized versions by providing locale-specific field data in write requests

Reference Behavior

Reference fields work seamlessly with localization, allowing different reference relationships for different language versions. This enables locale-specific content recommendations, region-appropriate product references, and localized navigation patterns.

Use Cases

  • Marketing Sites: Landing pages tailored to regional markets with localized messaging
  • Product Pages: E-commerce content adapted to local currencies, regulations, and preferences
  • Corporate Content: Company information, policies, and resources in multiple languages
  • Content Hubs: Resource centers and knowledge bases serving international audiences

Field Format Options

Pages support two localization formats depending on your organization's setup:

  • Single-language: Use direct fields object for accounts without localization
  • Multi-language: Nest field data under locale codes within the fields object (e.g., "en", "es")

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

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.