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.
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.
https://api.buttercms.com/v2/
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.
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.
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.
Create new items within a Collection using the Write API. Collections support completely dynamic schemas and multi-locale content, making them ideal for flexible content types like team members, products, or testimonials.
Dynamic Schema Flexibility: Collection fields are entirely user-defined through your dashboard configuration. The field structure in your request must match the schema you've configured for the specific collection, including field types, validation rules, and any required fields.
Locale Structure: For organizations without locales configured, provide field values directly in a flat structure. For multi-locale organizations, nest your field data under the appropriate locale codes (e.g., "en", "es") to create content in multiple languages simultaneously.
Media Integration: If Media
is the field_type for a chosen field, any URL can be provided as the field's value. The media corresponding to this URL will be automatically downloaded and uploaded to your ButterCMS media library, ensuring reliable hosting and CDN integration.
Asynchronous Processing: This endpoint returns 202 Accepted
immediately to ensure fast response times for your application. The actual item creation, including media uploads, validation, and any configured webhooks, happens in the background processing queue. See also: Architecture & Performance for guidance on levels
, pagination, and performance best practices.
Collection item data with dynamic field structure based on collection configuration and locale settings.
The unique identifier/slug of the Collection to create an item in.
Must match an existing collection in your organization.
Status of the collection item:
Defaults to "draft" if not specified.
Array of collection item data. Structure varies based on locale configuration:
Dynamic Nature: Field names and types are defined by your collection schema and can vary completely between collections.
https://api.buttercms.com/v2/content/
curl -i -X POST \
https://api.buttercms.com/v2/content/ \
-H 'Authorization: Bearer <YOUR_Token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"key": "team_members",
"status": "published",
"fields": [
{
"name": "John Doe",
"position": "Software Engineer",
"bio": "Experienced developer with expertise in web technologies",
"profile_image": "https://example.com/images/john-doe.jpg",
"years_experience": 5
}
]
}'
Accepted - Collection Item Creation Queued
The collection item has passed initial validation and creation has been queued for asynchronous processing.
Important: The item may not be immediately available in collection queries. Background processing includes:
If creation fails during background processing, contact support for assistance.
{ "status": "pending" }
Perform a full update (PUT) of an existing Collection item, completely replacing the item with the provided data. This operation is ideal when you need to ensure all fields are synchronized with your source data or when making comprehensive changes.
Update Method: PUT replaces the entire item with your request data, similar to recreating the item from scratch. This differs from PATCH operations, which only update specific fields. Use PUT when you want to ensure complete data consistency or when your workflow involves regenerating entire items.
Important: The URL must include a trailing slash after the item ID (e.g.,
/v2/content/my-collection/123/
). This is required for the endpoint to function correctly.
Item Identification: The unique item ID can be found in the meta
field of any collection item when retrieved through GET requests. This identifier remains constant throughout the item's life cycle and is required for all update and delete operations.
Reference Field Updates: When updating reference fields, use page slugs for Page references and item IDs for Collection references. To remove existing references, provide empty strings (""
), empty arrays ([]
), or null
values depending on the field type and whether it's a single or multi-reference field.
Asynchronous Processing: This endpoint returns 202 Accepted
immediately to ensure fast response times. The actual update processing, including media uploads, reference resolution, validation, and webhook triggers, happens in the background processing queue.
The unique identifier/slug of the Collection containing the item to update.
Must match an existing collection in your organization.
Status of the collection item:
Defaults to "draft" if not specified.
Optional for PATCH, Required for PUT. Collection item field data with flexible format support.
System automatically detects the format based on the structure of the object:
Without Locales Format: Direct field properties (e.g., name
, position
, bio
) With Locales Format: Locale codes as keys (e.g., en
, es
, fr
)
Update Behavior:
Dynamic Schema: Field names and types are completely user-defined based on your collection configuration.
Reference Fields: Support updating relationships to Pages and other Collections
"related_page": "example-slug"
)"tags": [1, 2, 3]
)""
, []
, or null
Media Fields: Support remote URL upload - content is automatically uploaded to ButterCMS
https://api.buttercms.com/v2/content/{collection_key}/{item_id}/
curl -i -X PUT \
https://api.buttercms.com/v2/content/team_members/123/ \
-H 'Authorization: Bearer <YOUR_Token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field1_key": "Updated field value",
"field2_key": "Another updated value",
"contact_email": "updated@example.com"
}
}'
{ "status": "pending" }
Perform a partial update (PATCH) of an existing Collection item, updating only the fields you specify while preserving all other content. This method is ideal for targeted updates without affecting the entire item structure.
Update Method: PATCH updates only the fields included in your request body, leaving all other fields unchanged. This differs from PUT operations, which replace the entire item. Use PATCH when you want to modify specific fields while preserving existing content, relationships, and metadata.
Partial Update Intelligence: Reference fields, status, timestamps, and any omitted content fields automatically retain their current values. This allows you to safely update specific content without worrying about accidentally clearing other important data.
Important: The URL must include a trailing slash after the item ID (e.g.,
/v2/content/my-collection/123/
). This is required for the endpoint to function correctly.
Item Identification: The unique item ID can be found in the meta
field of any collection item when retrieved through GET requests. This identifier remains constant throughout the item's life cycle.
Reference Field Handling: When updating reference fields, use page slugs for Page references and item IDs for Collection references. If you omit reference fields from your request, existing references remain completely unchanged, making it safe to update other content without affecting relationships.
Asynchronous Processing: This endpoint returns 202 Accepted
immediately to ensure fast response times. The actual update processing, including media uploads, reference validation, and webhook triggers, happens in the background processing queue.
The unique identifier/slug of the Collection containing the item to update.
Must match an existing collection in your organization.
Status of the collection item:
Defaults to "draft" if not specified.
Optional for PATCH, Required for PUT. Collection item field data with flexible format support.
System automatically detects the format based on the structure of the object:
Without Locales Format: Direct field properties (e.g., name
, position
, bio
) With Locales Format: Locale codes as keys (e.g., en
, es
, fr
)
Update Behavior:
Dynamic Schema: Field names and types are completely user-defined based on your collection configuration.
Reference Fields: Support updating relationships to Pages and other Collections
"related_page": "example-slug"
)"tags": [1, 2, 3]
)""
, []
, or null
Media Fields: Support remote URL upload - content is automatically uploaded to ButterCMS
https://api.buttercms.com/v2/content/{collection_key}/{item_id}/
curl -i -X PATCH \
https://api.buttercms.com/v2/content/team_members/123/ \
-H 'Authorization: Bearer <YOUR_Token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"status": "published",
"fields": {
"field2_key": "Only this field gets updated"
}
}'
{ "status": "pending" }
Delete an existing Collection item using a soft delete operation, which marks the item as deleted while preserving the data for potential recovery. This approach ensures data safety while removing items from public API responses.
Soft Delete Behavior: The item is marked as deleted in the system and will no longer appear in collection listings, search results, or standard API responses. However, the actual data is preserved in the database, allowing for potential recovery through support channels if needed.
Important: The URL must include a trailing slash after the item ID (e.g.,
/v2/content/my-collection/123/
). This is required for the endpoint to function correctly.
Item Identification: The unique item ID can be found in the meta
field of any collection item when retrieved through GET requests. This identifier is required to specify which item to delete.
Request Body: DELETE requests should not include any request body data - send an empty body or omit the body entirely. The item ID in the URL path is sufficient to identify the target item.
Asynchronous Processing: This endpoint returns 204 No Content
immediately upon successful request validation. The actual deletion processing, including webhook notifications and reference cleanup, happens in the background processing queue.
https://api.buttercms.com/v2/content/{collection_key}/{item_id}/
curl -i -X DELETE \
https://api.buttercms.com/v2/content/team_members/123/ \
-H 'Authorization: Bearer <YOUR_Token_HERE>'
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.
Generate XML feeds for content syndication and SEO.
All feeds can be filtered by category or tag and include only published content from your organization.
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:
https://cdn.buttercms.com/3ccPHhYHTNK2zQ14gCOy
https://cdn.buttercms.com/resize=width:100,height:100/3ccPHhYHTNK2zQ14gCOy
For complete transformation options and parameters, see the full Filestack documentation.