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/
Content Types
The ButterCMS 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. Pages can be either Single Pages (unique pages like Homepage) or Page Types (templated pages like blog posts or product pages).
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. Collections are optimized for simpler data structures and faster querying, making them ideal for content that needs to be referenced by Pages or queried directly from the API.
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 and includes features like automated RSS feeds and WordPress import capabilities.
API Architecture
ButterCMS provides a REST API that serves content through a globally distributed infrastructure. Content created through the dashboard or Write API is immediately available via read endpoints with automatic global distribution for optimized delivery.
Content Types
The API serves three primary content types: Pages (individual web content), Collections (structured data tables), and Blog Posts (chronological content with built-in categorization and authoring features).
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Pages │◄────▶│ Collections │◄────▶│ Blog Posts │
│ │ │ │ │ │
│ • Single Pages │ │ • Categories │ │ • Authors │
│ • Page Types │ │ • Products │ │ • Categories │
│ │ │ • Team Members │ │ • Tags │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└─────────────────────────┼─────────────────────────┘
│
Reference Fields (slugs/IDs)
One-to-One or One-to-ManyPublication States
Content can exist as draft (accessible via preview), published (live via API endpoints), or scheduled (automatic publication). State changes trigger system-wide operations including cache invalidation, webhook notifications, and reference resolution across related content. Note: Pages support true three-state lifecycle with versioned drafts and scheduling; Blog posts have simplified state management without draft-over-published versioning.
┌─────────────┐ Publish ┌─────────────┐ Schedule ┌─────────────┐
│ Draft │──────────────▶│ Published │──────────────▶│ Scheduled │
│ │ │ │ │ │
│ • Preview │◄──────────────┤ • Live API │◄──────────────┤ • Auto-pub │
│ • Editable │ Unpublish │ • Cached │ Update │ • Queued │
└─────────────┘ └─────────────┘ └─────────────┘All content types follow a unified publication state system where content can be draft (accessible via preview), published (live via standard API endpoints), or scheduled (automatically published at specified times through dashboard configuration). Write API operations return immediate 202 Accepted responses while background systems handle media processing, validation, webhook notifications, and cache invalidation.
Important Differences
Pages support true three-state lifecycle with versioned drafts and scheduling, allowing new draft versions over existing published content. Blog posts have simplified state management without draft-over-published versioning capabilities.
Request Flow
Read operations query cached content from edge locations, while write operations process through the primary API and trigger cache invalidation. All write operations return immediate responses (202 Accepted) and initiate background processes to handle resource-intensive tasks like media processing and webhook delivery.
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ Client │───▶│ Global CDN │───▶│ ButterCMS │───▶│ Background │
│ Application │ │ (150+ edges) │ │ API │ │ Processing │
└─────────────┘ └──────────────┘ └─────────────┘ └──────────────┘
│ │ │
Cache Hit (50-100ms) Cache Miss Media Upload
┌──────────────┐ (200-500ms) Validation
│ Cached │ Webhooks
│ Response │ Cache Refresh
└──────────────┘Authentication
Read operations use query parameter authentication (auth_token), while write operations require header-based token authentication. This separation allows for secure content management while enabling efficient public content delivery.
Performance and Caching
Content delivery operates through a global CDN with 150+ edge locations. Read operations are cached for 20 days at edge locations by default, providing sub-100ms response times for cached content worldwide.
Cache Behavior
Initial requests fetch content from the API and populate edge caches (~200-500ms). Subsequent requests serve from the nearest location (~50-100ms). Content updates automatically invalidate relevant cache entries globally, including all content that references the changed content.
Reference Serialization Performance
When cached content is unavailable, the API serializes both the requested content and all content referenced by the requested content at the depth specified by the levels parameter. For list endpoints, this can create substantial serialization work—requesting 100 pages with references may require serializing 100+ individual objects plus their references. Use levels=1 for list operations to minimize this overhead.
List Request (levels=2):
┌─────────────┐
│ 100 Pages │ ──────┐
└─────────────┘ │
▼
┌─────────────────────┐
│ Serialization Load │
│ │
│ Page 1 + refs (3) │ ──┐
│ Page 2 + refs (5) │ │
│ Page 3 + refs (2) │ │ Exponential
│ ... │ │ Growth
│ Page 100 + refs (4) │ │
│ │ │
│ Total: 400+ objects │ ◄─┘
└─────────────────────┘
Solution: Use levels=1 for listsCache Invalidation
Content changes (create, update, delete, and status changes) trigger multi-layer cache invalidation including object cache, serialized response cache, and global CDN cache. Referenced content invalidation cascades automatically—when a referenced object changes, all content that references it also gets invalidated to maintain consistency.
Content Update:
┌─────────────┐
│ Page A │ (updated)
└─────────────┘
│
▼ triggers invalidation
┌─────────────────────────────────────┐
│ Cache Layers │
│ ┌─────────────────────────────────┐ │
│ │ Object Cache │ ✗ Invalid │ │
│ ├─────────────────────┼───────────┤ │
│ │ Response Cache │ ✗ Invalid │ │
│ ├─────────────────────┼───────────┤ │
│ │ Global CDN Cache │ ✗ Invalid │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────┘
│
▼ cascades to
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Page B │ │Collection C │ │ Page D │
│(refs Page A)│ │(refs Page A)│ │(refs Page A)│
└─────────────┘ └─────────────┘ └─────────────┘
All referencing content also invalidatedOptimization Parameters
For Blog list/search endpoints, use exclude_body=true to reduce response size by 50-70%. Control reference resolution depth with levels=1 to levels=5 (default 2) to balance response completeness with performance. Implement efficient pagination patterns for large content sets to avoid expensive serialization of deeply referenced content.
Write Operations
Create and update operations return 202 Accepted for immediate feedback while background processing handles tasks like media uploads, validation, and webhook notifications. This ensures consistent fast response times regardless of operation complexity.
Integration Best Practices
For easiest implementation, ButterCMS API integration should follow a structured approach of these sequential steps: content architecture planning, API endpoint integration, performance optimization, and production deployment. Content must be designed in your ButterCMS dashboard first to establish schema and reference relationships before implementing API calls in your application.
Static Site Generation (SSG) implementations fetch content during build processes and utilize webhook-triggered rebuilds for content updates. This pattern provides maximum performance through pre-built pages and CDN distribution but requires build system integration for content synchronization. Build-time fetching typically uses batch API calls to retrieve all necessary content, implementing error handling for API availability during build processes.
Server-Side Rendering (SSR) applications fetch content on each request, implementing application-level caching to optimize performance while maintaining real-time content updates. Request-time fetching allows for personalized content and immediate content updates but requires careful cache management and error handling for API unavailability scenarios.
Single Page Applications (SPA) implement client-side content fetching with progressive loading patterns, utilizing browser caching and API response caching for optimal user experience. Client-side integration enables dynamic content updates and interactive experiences but requires consideration of API key security and CORS configuration.
┌─────────────────────────────────────────────────────────────────┐
│ Integration Patterns │
├─────────────────────────────────────────────────────────────────┤
│ │
│ SSG (Build Time): │
│ Content ──▶ Build Process ──▶ Static Files ──▶ CDN ──▶ Users │
│ ▲ │
│ Webhook triggers rebuild │
│ │
│ SSR (Request Time): │
│ User Request ──▶ Server ──▶ API Call ──▶ Dynamic Page ──▶ User │
│ │ │
│ ▼ App-level cache │
│ │
│ SPA (Client Side): │
│ User ──▶ App Shell ──▶ API Calls ──▶ Dynamic Updates ──▶ UI │
│ │ │
│ ▼ Browser cache │
└─────────────────────────────────────────────────────────────────┘API Efficiency
Strategic parameter usage improves performance significantly. The exclude_body=true parameter reduces response size by 50-70% for content listing operations, while the levels parameter controls reference depth to balance data completeness with response time. Pagination should be implemented using appropriate page sizes for large content sets, typically 10-25 items per request for optimal performance.
Error Handling
Implement graceful degradation patterns for API unavailability, retry logic with exponential backoff for transient failures, and fallback content mechanisms for critical application functionality. Applications should monitor API response times and implement circuit breaker patterns for sustained API issues. Content architecture should minimize reference depth requirements and design reference patterns to avoid circular dependencies that impact API performance.
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.
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.