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.
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.
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/
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
Overview
E-mail
License
Languages
Servers
ButterCMS API v2
https://api.buttercms.com/v2/
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.
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:
- Developer Phase: Define component schemas in ButterCMS dashboard with specific field types and structures
- Content Phase: Content creators populate component fields with data using dashboard or Write API
- 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
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.
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 - 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
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.