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.
Predefined Blog Schema
ButterCMS Blog Posts use a standardized, predefined schema that provides out-of-the-box functionality for chronological content with built-in organizational and authoring features.
Standardized Field Structure
Blog Posts come with a predefined set of fields that cannot be modified through the dashboard or API. This standardization ensures consistency across all blog content and enables built-in features that work reliably across all ButterCMS accounts.
Core Blog Fields
- Title: SEO-optimized title field with automatic URL slug generation
- Body: Rich HTML content field supporting full editorial formatting
- Summary: Optional excerpt field for post previews and social sharing
- Featured Image: Dedicated image field with automatic CDN optimization
- SEO Metadata: Built-in meta title, meta description, and Open Graph fields
- Publication Date: Automatic timestamp management with scheduling capabilities
- Status: Draft, published, and scheduled state management
Content Richness
The body field supports comprehensive HTML content including embedded media, formatted text, links, and other rich content elements that enable full editorial expression within the standardized structure.
SEO Integration
Blog Posts include built-in SEO optimization features such as automatic XML sitemap generation, RSS feed creation, and structured data markup that enhance search engine discoverability without additional configuration.
Built-in Categorization and Tagging
Blog Posts provide sophisticated organizational capabilities through predefined categorization and tagging systems that enable flexible content discovery and filtering.
Categories System
- Hierarchical Organization: Categories support parent-child relationships for sophisticated content taxonomy
- URL Integration: Categories automatically generate SEO-friendly URLs for category pages
- Filtering Capability: API endpoints support category-based filtering for content queries
- RSS Integration: Category-specific RSS feeds are automatically generated
Tagging System
- Flexible Labeling: Tags provide flexible, non-hierarchical content labeling for cross-cutting themes
- Tag-based Discovery: Readers can discover related content through tag-based navigation
- API Filtering: Tags support API filtering for precise content queries
- Tag Clouds: Automatic tag frequency calculation for tag cloud generation
Organizational Benefits
The combination of categories and tags enables sophisticated content organization that supports both hierarchical browsing (categories) and thematic discovery (tags), providing multiple pathways for content access.
Content Strategy Integration
Use categories for broad content themes and permanent organizational structure, while using tags for specific topics, campaigns, or temporal content connections that may evolve over time.
Predefined Metadata and Features
Blog Posts include comprehensive metadata and built-in features that eliminate the need for custom field configuration while providing professional blogging capabilities.
Author Management
- Author Profiles: Dedicated author entities with names, biographies, profile images, and social links
- Multi-author Support: Blog posts can be attributed to multiple authors for collaborative content
- Author Archives: Automatic generation of author-specific content archives and RSS feeds
- API Access: Author information is accessible through dedicated API endpoints
Publication Metadata
- Creation Timestamps: Automatic tracking of content creation time
- Publication Dates: Separate publication date management for editorial calendar control
- Update Tracking: Last modified timestamps for content freshness indication
- URL Slug Management: Automatic SEO-friendly URL generation with manual override capability
Built-in Features
- RSS Feeds: Automatic RSS 2.0 and Atom feed generation for content syndication
- XML Sitemaps: Search engine sitemap integration for improved discoverability
- Previous/Next Navigation: Automatic post navigation for chronological content browsing
- Related Posts: Built-in content relationship suggestions based on categories and tags
Social Media Integration
Blog Posts include Open Graph and Twitter Card metadata that ensure proper social media presentation when content is shared across platforms.
Publication States and Workflow
Blog Posts follow a simplified publication state system optimized for editorial workflows and content scheduling, with important differences from Pages regarding versioning capabilities.
Simplified State Management
Blog Posts use a streamlined three-state system (draft, published, scheduled) without the complex versioning capabilities available to Pages. This simplification supports efficient editorial workflows focused on chronological content publication.
State Characteristics
- Draft State: Content accessible only through preview mode, enabling editorial review and revision
- Published State: Content live and accessible through all blog endpoints with full CDN caching
- Scheduled State: Content automatically published at specified times through dashboard scheduling
Versioning Limitations
Unlike Pages, Blog Posts do not support creating draft versions over existing published content. Once published, posts can be unpublished (returned to draft state) but cannot maintain simultaneous draft and published versions.
Editorial Workflow
The simplified state system supports traditional blog editorial workflows where content moves linearly from draft to published, with scheduling capabilities for time-based publication strategies.
Publication Behavior
Blog Posts are created and published immediately when using the Write API unless explicitly set to draft status, supporting both automated content creation and editorial review workflows.
Localization Limitations and Alternatives
No Native Localization: Blog Posts do not support the multi-language localization features available to Pages and Collections. The predefined blog schema is designed for single-language content within each ButterCMS account.
Alternative Approach for International Content: Organizations requiring multi-language blog functionality should consider using Page Types instead of Blog Posts. Page Types can be configured to replicate blog functionality while providing full localization support.
Page Type Blog Implementation
- Custom Schema: Create Page Types with blog-like fields (title, body, date, author references)
- Localization Support: Page Types inherit full localization capabilities from the Pages system
- Component Integration: Page Types can include components for rich content layouts beyond traditional blog formats
- Reference Integration: Page Types can reference Collections for author information, categories, and tags
Migration Considerations
Organizations planning international blog expansion should evaluate Page Types early in their content strategy to avoid complex migration scenarios from Blog Posts to Pages.
Single-Language Optimization: For single-language blog content, Blog Posts provide optimal performance and built-in features that eliminate the need for custom field configuration and development overhead.
Content Import Capabilities
WordPress Import: ButterCMS provides built-in WordPress import functionality that enables migration from WordPress blogs to ButterCMS Blog Posts while preserving content structure, metadata, and organizational elements.
Import Features
- Content Preservation: Blog post titles, bodies, publication dates, and metadata are transferred accurately
- Category Migration: WordPress categories are mapped to ButterCMS categories with hierarchy preservation
- Tag Transfer: WordPress tags are converted to ButterCMS tags maintaining content relationships
- Author Mapping: WordPress authors are created as ButterCMS author entities with profile information
- Media Import: WordPress media attachments are transferred to ButterCMS media library with CDN integration
Import Planning: WordPress import is a one-time migration tool that requires careful planning for large content volumes and complex category structures. Consider content review and cleanup processes as part of migration workflows.
Post-Import Optimization: After WordPress import, leverage ButterCMS features such as CDN optimization, enhanced SEO metadata, and API access to improve content performance and integration capabilities beyond original WordPress functionality.
Blog API Characteristics
Optimized Endpoints: Blog Post APIs are optimized for chronological content access patterns with built-in pagination, sorting, and filtering capabilities that support common blog functionality requirements.
Performance Features
- Body Exclusion: Use
exclude_body=trueparameter to reduce response size by 50-70% for listing operations - Category Filtering: Native support for category-based content filtering without complex query construction
- Tag Filtering: Built-in tag filtering for precise content queries
- Date Range Queries: Support for publication date filtering to build archive functionality
Integration Patterns
Blog Post APIs are designed for traditional blog functionality including archive pages, category browsing, tag discovery, author profiles, and RSS feed generation, providing comprehensive blog platform capabilities through standardized endpoints.
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.