Core design principles
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.RESTful design
The ButterCMS API follows REST (Representational State Transfer) architecture, which means:- Resource-Oriented URLs: Each URL represents a specific resource (pages, collections, posts)
- HTTP Methods: Standard HTTP verbs indicate the action (GET for reading, POST for creating, PUT/PATCH for updating, DELETE for removing)
- Stateless Requests: Each request contains all information needed to process it
- JSON Responses: All responses use JSON format for consistency and ease of parsing
Base URL
All API requests are made to:Architecture overview
Content types
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. 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.Global CDN infrastructure
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.Request flow
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
Publication states
Content can exist in three states:| State | Description | Access |
|---|---|---|
| Draft | Content being edited, not yet live | Preview mode only (preview=1) |
| Published | Live content accessible via API | Standard API endpoints |
| Scheduled | Automatic publication at specified time | Preview until publication time |
Write operations
Create and update operations return202 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 patterns
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)
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.API efficiency
Strategic parameter usage improves performance significantly:exclude_body=true: Reduces response size by 50-70% for content listing operationslevelsparameter: Controls reference depth (1-5, default 2) to balance data completeness with response time- Pagination: Use 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.Key features summary
| Feature | Description |
|---|---|
| REST Architecture | Predictable, resource-oriented URLs |
| JSON Responses | All responses in JSON format |
| Global CDN | 150+ edge locations worldwide |
| Fast Responses | Sub-100ms for cached content |
| Automatic Caching | 20-day edge cache with smart invalidation |
| Webhooks | Real-time notifications for content changes |
| Localization | Multi-language content support |
Next steps
Authentication
Learn how to authenticate your API requests
REST Endpoints
Explore all available API endpoints
Request/Response Format
Understand the JSON data structure
Error Handling
Handle errors gracefully