Skip to content

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
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.

Overview and Core Features

Collections serve as your structured data foundation, providing tables of organized content designed for reference by Pages or direct API queries. Collections excel at managing reusable data that supports and enhances your primary content.

Core Collection Characteristics

  • ID-based Retrieval: Numeric ID identification system for precise, efficient data access
  • Optimized Structure: Streamlined schemas focused on data integrity and query performance
  • Reference-Oriented: Designed primarily to be referenced by Pages and other content types
  • Simplified Management: Straightforward field structures without component complexity
  • Flexible Schemas: Completely customizable field definitions to match your data requirements

Collections vs. Pages Comparison

  • No Components: Collections do not support individual components, component picker fields, or component libraries
  • No Repeaters: Collections cannot use repeater field types that allow multiple instances of field structures
  • No Form Integrations: Direct form service integrations are not available for Collections
  • Simpler Updates: Streamlined update patterns without component-specific update behaviors
  • Performance Focus: Optimized for faster querying and smaller response sizes

Ideal Use Cases

  • Categories and Tags: Organizational taxonomies for content classification
  • Team Members: Staff directories with contact information, roles, and expertise
  • Product Catalogs: Basic product information that Pages can reference and expand upon
  • Location Data: Store and office information for multi-location organizations
  • Reference Lists: Any structured data that enhances content without requiring complex layouts

Content Publication States

Collections follow the same unified publication state system as other ButterCMS content types, with implementation details optimized for data management workflows.

  • Draft State: Collection items can be created and edited in draft status, allowing data validation and review processes before making content live. Draft items are accessible only through preview mode, enabling data verification workflows.
  • Published State: Published collection items are available through standard API endpoints and can be referenced by Pages and other content. Published collections benefit from full CDN caching and global distribution for optimal performance.
  • Scheduled State: Collection items support scheduled publication for time-based data release, enabling coordinated content launches and editorial calendar integration.

Publication Workflow

Collection publication states integrate seamlessly with Page and Blog publication workflows, allowing coordinated content releases where Pages can reference Collections that publish simultaneously.

State Management

Collection items support standard state transitions (draft to published, published to draft, scheduled publication) through both dashboard interface and Write API operations.


Previewing

Preview functionality enables data validation and quality assurance for draft collection items before publication, supporting content review processes and data accuracy verification.

Collections Preview Strategy

Enable preview mode in development, staging, and testing environments by adding preview=1 to Collection API requests. This allows teams to validate draft collection items in application context before publication.

Data Validation Workflow

  1. Create or update collection items in draft status
  2. Use preview mode to fetch draft items through API calls
  3. Validate data structure, content accuracy, and integration behavior
  4. Review how draft items appear when referenced by Pages
  5. Publish collection items after validation confirms expected behavior

Environment Integration

Consider implementing environment-based configuration that automatically includes the preview parameter in non-production environments, enabling seamless data validation workflows across different deployment contexts.

Reference Preview

When previewing Pages that reference Collections, use preview mode to ensure both the Page draft and any referenced Collection drafts are displayed accurately, providing complete content preview scenarios.

API Behavior

When preview=1 is included in Collection API requests, ButterCMS returns the latest draft version of collection items rather than published versions, enabling comprehensive content validation workflows.

Reference Architecture

Collections serve as both reference targets and reference sources within ButterCMS's content relationship system, enabling sophisticated data organization and content connections.

Collection-to-Page References

Collection items can reference Pages using page slugs, creating bidirectional content relationships that support navigation, feature highlighting, and content discovery patterns.

Implementation Patterns

  • Featured Content: "featured_page": "landing-page-slug" for highlighting specific pages
  • Related Resources: "related_pages": ["guide-1-slug", "guide-2-slug"] for content series
  • Landing Page Association: "product_page": "product-details-slug" for e-commerce integration

Collection-to-Collection References

Collection items can reference other collection items using numeric IDs, enabling hierarchical data structures and complex organizational patterns.

Organizational Examples

  • Hierarchical Categories: "parent_category": 123 for taxonomy structures
  • Related Items: "related_products": [456, 789, 101] for cross-selling and recommendations
  • Team Relationships: "department": 234 for organizational structure
  • Location Hierarchies: "region": 345 for geographic organization

Collection Reference Management

Adding References

Provide appropriate identifiers in Write API requests—page slugs for Page references, numeric IDs for Collection references. The system validates reference targets during processing.

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 relationship updates
  • PUT requests: Provide all fields including references; full replacement semantics apply to Collections

Reference Validation

Collection reference fields are validated to ensure target content exists and is accessible, preventing broken relationships in your content architecture.


Reference Levels

The levels parameter controls reference field depth in Collection API responses, optimizing data delivery for different use cases while managing response size and performance.

Parameter Configuration for Collections

  • Default: levels=2 provides complete referenced data for most collection use cases
  • Range: 1-5 (values outside this range are automatically adjusted)
  • Level 1: Reference fields return API URIs only (optimal for collection listings)
  • Level 2+: Reference fields return complete object data (ideal for detailed displays)
  • Level 5 (max): Returns URIs for any remaining references beyond specified depth

Collection-Specific Performance Guidelines

  • Use levels=1 for collection listings or when building dropdown/select options
  • Use levels=2 (default) for individual collection item display with reference context
  • Use levels=3-5 when displaying collections with deep reference chains
  • Pagination Considerations: Use levels=1 for paginated collection lists to minimize serialization overhead

Response Format Examples

Level 1 Response (URIs for minimal data transfer)

{
  "data": [
    {
      "meta": {"id": 123},
      "name": "Technology",
      "related_items": ["/v2/content/?keys=categories[_id=456]"],
      "featured_page": ["/v2/pages/product-guides/tech-overview"]
    }
  ]
}

Level 2+ Response (Complete objects for rich data access)

{
  "data": [
    {
      "meta": {"id": 123},
      "name": "Technology",
      "related_items": [
        {"meta": {"id": 456}, "name": "Software", "description": "..."}
      ],
      "featured_page": [
        {"slug": "tech-overview", "fields": {"title": "Technology Guide", "summary": "..."}}
      ]
    }
  ]
}

Cross-Content Type References

The levels parameter works consistently whether references point to Pages or other Collections, providing predictable behavior across your entire content architecture.

Localization and Best Practices

Localization

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

Account Configuration

Locale support must be configured in your ButterCMS account settings before creating multi-language collections. Each locale uses an API slug (such as en, es, fr) defined during account setup.

Important Limitation: Once locales are added to an account, they cannot be removed. Plan your internationalization approach carefully before configuration to avoid schema constraints.

Content Versions

Collections can maintain separate content versions for each configured locale, allowing the same data structure to serve different language markets while preserving field schemas and reference relationships.

API Integration Patterns

  • Specify locale: Add locale=en parameter to retrieve collection items 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 Localization: Reference fields work seamlessly with localization, allowing different reference relationships for different language versions. This enables locale-specific data associations, region-appropriate content relationships, and localized organizational structures.

Collection Localization Use Cases

  • Product Catalogs: International product information with localized descriptions, pricing, and availability
  • Team Directories: Multi-regional staff information with localized roles and contact details
  • Category Systems: Taxonomies adapted to regional content organization and cultural preferences
  • Location Data: Multi-language address information, operating hours, and regional service details

Field Data Organization

Collections support two localization formats:

  • Single-language: Use direct field values for accounts without localization enabled
  • Multi-language: Nest field data under locale codes for accounts with localization (e.g., fields organized by "en", "es", "fr" keys)

Best Practices

Localization Best Practices

  • Consistent References: Maintain reference relationships across locales where appropriate, or create locale-specific references when regional variations are needed
  • Data Validation: Validate localized collection data to ensure completeness across all configured locales
  • Reference Planning: Design reference patterns that work effectively across different language and cultural contexts

Performance Optimization

  • Use appropriate levels parameters: Start with levels=1 for listing operations and increase only when necessary
  • Implement pagination: For large collections, use pagination to maintain responsive API performance
  • Cache strategically: Leverage ButterCMS CDN caching for frequently accessed collection data

Content Architecture

  • Design for scale: Plan collection schemas that can accommodate future data requirements
  • Reference strategy: Create logical reference patterns that support your content relationships
  • Validation planning: Use appropriate field validation to maintain data quality across collection items

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.