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.

Component System Overview

Components provide a structured approach to building dynamic page layouts with reusable, predefined content blocks. This system enables content creators to build complex pages using consistent, developer-defined structures while maintaining design integrity and content organization.

Component Architecture

Components in ButterCMS consist of predefined field schemas that developers configure in the dashboard, which content creators then populate with data. This separation ensures consistent data structure while providing content flexibility.

Schema Management

Component schemas must be predefined in your ButterCMS dashboard before use. Unlike other field types, components cannot be created or modified through the Write API—they require dashboard configuration to establish field structures, validation rules, and presentation parameters.

Content Creation Workflow:

  1. Developer Phase: Define component schemas in ButterCMS dashboard with specific field types and structures
  2. Content Phase: Content creators populate component fields with data using dashboard or Write API
  3. Delivery Phase: API responses include structured component data for rendering in your application

Individual Components

Single, structured content blocks within your page schema that maintain consistent field structures while allowing dynamic content updates. Individual components are ideal for standardized content sections with predictable data requirements.

Field Organization

Individual component fields are organized as nested JSON objects that preserve the component's internal structure while remaining easily accessible through API responses.

{
  "hero": {
    "image": "https://example.com/hero-image.jpg",
    "alt_text": "Hero section background image",
    "headline": "Welcome to Our Platform",
    "subtitle": "Powerful content management made simple",
    "cta_button": {
      "text": "Get Started",
      "url": "/signup"
    }
  }
}

Update Behavior

Individual component fields support selective updates using PATCH requests, allowing you to modify specific component properties without affecting other fields within the same component or other components on the page.

Example Update Request:

{
  "fields": {
    "hero": {
      "headline": "Updated Welcome Message"
    }
  }
}

In this example, only the headline field is updated while image, alt_text, subtitle, and cta_button retain their existing values.

Use Cases:

  • Header Sections: Consistent hero areas with image, headline, and call-to-action elements
  • Contact Information: Standardized contact blocks with address, phone, and email fields
  • Feature Highlights: Structured feature presentations with icons, titles, and descriptions
  • Testimonials: Consistent testimonial formats with quotes, attribution, and images

Component Picker Fields

Component picker fields combine multiple predefined components in an ordered array, enabling dynamic page layouts with mixed content types. This functionality is essential for creating flexible, editorial-friendly pages where content structure can vary based on specific needs.

Dynamic Layout Structure

Component picker fields allow content creators to select from available component types and arrange them in any order, providing maximum layout flexibility while maintaining structured data integrity.

Array-Based Organization

Each element in a component picker array represents a single component instance with its type identifier and associated field data:

{
  "sections": [
    {
      "faq_item": {
        "question": "Are dogs allowed in the facility?",
        "answer": "Leashed dogs are welcome in all common areas and outdoor spaces.",
        "category": "Pets",
        "featured_image": "https://example.com/dog-friendly.jpg"
      }
    },
    {
      "trivia_block": {
        "title": "Did You Know?",
        "facts": [
          "Our facility was built in 1892",
          "We've hosted over 10,000 events"
        ],
        "background_color": "blue"
      }
    },
    {
      "image_gallery": {
        "title": "Recent Photos",
        "images": [
          {
            "url": "https://example.com/photo1.jpg",
            "caption": "Summer event 2024"
          },
          {
            "url": "https://example.com/photo2.jpg",
            "caption": "Holiday celebration"
          }
        ]
      }
    }
  ]
}

Component Type Selection

Each component in a picker field is identified by its type key (faq_item, trivia_block, image_gallery in the example above), which corresponds to component schemas configured in your ButterCMS dashboard.

Update Limitations

Component picker fields require complete array replacement when updating. You cannot partially update individual components within a picker field—any update must include the entire array contents with all components and their complete field data.

Complete Update Example:

{
  "fields": {
    "sections": [
      {
        "faq_item": {
          "question": "Updated question text",
          "answer": "Updated answer with more detail",
          "category": "Updated Category",
          "featured_image": "https://example.com/new-image.jpg"
        }
      },
      {
        "trivia_block": {
          "title": "New Trivia Section",
          "facts": ["New fact one", "New fact two"],
          "background_color": "green"
        }
      }
    ]
  }
}

Ordering and Management

The order of components in the array determines their display sequence, giving content creators control over page flow and information hierarchy. Components can be reordered by changing their position in the array.

Use Cases:

  • Landing Pages: Mixed content sections with headers, features, testimonials, and calls-to-action
  • Resource Pages: Combination of text blocks, image galleries, downloads, and embedded content
  • Event Pages: Dynamic sections for schedules, speakers, locations, and registration information
  • Product Pages: Flexible layouts combining specifications, images, reviews, and related products

Advanced Features

Media Integration

Components seamlessly integrate with ButterCMS media management system, enabling automatic media processing and CDN optimization for component-based content.

Media Field Support

When a component field is configured with Media field type, any URL provided as the field value triggers automatic media processing, including download, upload to ButterCMS media library, and CDN integration.

Automatic Processing

Remote image URLs provided in media fields are automatically downloaded and uploaded to your ButterCMS media library, ensuring reliable hosting, CDN delivery, and centralized media management.

Example Media Integration:

{
  "hero_section": {
    "background_image": "https://external-site.com/image.jpg",
    "logo": "https://company-assets.com/logo.png"
  }
}

After processing, these external URLs are replaced with ButterCMS CDN URLs, providing optimized delivery and eliminating external dependencies.

CDN Benefits

Media processed through components receives full CDN integration including global distribution, automatic optimization, and image transformation capabilities through Filestack integration.

Media Management

All component media becomes part of your centralized ButterCMS media library, enabling reuse across multiple pages and providing centralized organization and management capabilities.


Component Development Guidelines

Schema Design

Design component schemas with reusability and flexibility in mind. Consider common use cases and provide appropriate field types that balance structure with content creator freedom.

Field Validation

Leverage ButterCMS field validation options within component schemas to ensure data quality and consistency across component instances.

Naming Conventions

Use clear, descriptive names for component types and fields that help content creators understand purpose and expected content without requiring extensive documentation.

Performance Considerations

Design components with appropriate granularity—overly complex components can impact API response times, while overly simple components may require excessive API calls for complete page rendering.

Content Creator Experience

Consider the dashboard editing experience when designing components, ensuring that field order and grouping create intuitive content creation workflows.

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.