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.
- Update Blog Post via Write API
Create Blog Post via Write API
Delete Blog Post via Write API
Update Blog Post via Writ...
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.
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
Request
Create a new blog post using the Write API with support for rich media, categorization, and automatic author assignment. This endpoint enables programmatic content creation for blogs, news sites, and content management workflows.
Required Fields: Every blog post must include a title (post title) and slug (URL-friendly identifier). The slug must be unique across all posts in your organization and will become part of the post's permanent URL.
Author Management: The author must already exist in your ButterCMS account before creating posts. You can specify the author by email address or slug. If no author is specified, the post will be automatically assigned to your organization owner, ensuring every post has proper attribution.
Dynamic Categorization: Categories and tags can be provided as string arrays in your request. If you specify categories or tags that don't exist yet, they will be automatically created in your account, making it easy to expand your content taxonomy organically.
Media Integration: Featured images are always uploaded to your ButterCMS media library for reliable hosting. For images within the post body content, set upload_images_to_media_library=true to automatically download and host external images through ButterCMS's CDN infrastructure.
Publication & Scheduling: Blog posts default to draft unless status=published is provided. Scheduling future publication is not supported via the Write API; scheduling-related fields will result in validation errors.
Asynchronous Processing: This endpoint returns 202 Accepted immediately to ensure fast response times for your application. The actual post creation, including media processing, category creation, and webhook notifications, happens in the background processing queue.
Security
writeTokenAuth
The slug of the blog post (must be unique).
Auto-Generation: If not provided, the slug will be automatically generated from the title using unicode slugification. You can provide a custom slug or let the API generate one for you.
Example: "this-is-a-blog-post"
The status of the post. Defaults to 'draft'. Cannot be 'scheduled'.
Default "draft"
Enum"draft""published"
Example: "published"
One of:
Author reference for blog posts. Author must exist in your account prior to POST.
You can specify the author either by email or by slug. If no author is specified, defaults to the organization owner.
Array of category names. Categories will be created if they don't exist.
Example: ["Recipes","Meals"]
Array of tag names. Tags will be created if they don't exist.
Example: ["Butter","Sushi","Really Good Recipes"]
Can be a remote URL to an image.
The image will always be uploaded to the media library (the value of upload_images_to_media_library is ignored for featured images).
Example: "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg"
Alt text for the featured image
Example: "Featured image alt text example."
Should be a string of escaped HTML.
In case it contains any remote URLs to images, the upload_images_to_media_library flag controls the behavior.
Example: "<h1>Butter</h1><p>I am so hungry!</p>"
Plain-text summary of the blog post
Example: "This is a blog post summary."
Meta description for SEO and social sharing
Example: "This is a blog post to test the API."
Defaults to false.
If set to true, any image URLs in the body property will be uploaded to the Butter Media Library and the original URL will be replaced with the media library URL.
Note: Featured images are always uploaded regardless of this setting.
Default false
Example: false
- ButterCMS API v2
https://api.buttercms.com/v2/posts/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://api.buttercms.com/v2/posts/ \
-H 'Authorization: Bearer <YOUR_Token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"title": "This is a blog post",
"slug": "this-is-a-blog-post",
"status": "published",
"author": {
"email": "your@author.com"
},
"categories": [
"Recipes",
"Meals"
],
"tags": [
"Butter",
"Sushi",
"Really Good Recipes"
],
"featured_image": "https://farm1.staticflickr.com/836/42903355654_8faa21171a_m_d.jpg",
"featured_image_alt": "Featured image alt text example.",
"body": "<h1>Butter</h1><p>I am so hungry!</p>",
"summary": "This is a blog post summary.",
"seo_title": "This is a blog post",
"meta_description": "This is a blog post to test the API.",
"upload_images_to_media_library": false
}'Accepted - Post Creation Initiated
A validated POST request will return a response with HTTP status code 202. Full post creation occurs asynchronously, meaning a successfully created post may not show immediately.
Posts are validated prior to returning the API response but it is also possible that post creation may fail after returning a 202 response. If this happens please contact support.
Response
application/json
{ "status": "pending" }
Request
Update an existing blog post using partial updates, allowing you to modify specific fields while preserving all other content. This endpoint is perfect for content updates, SEO optimization, or adding new media to existing posts.
Partial Update Flexibility: All fields in the request body are optional - include only the fields you want to modify. Any omitted fields will retain their current values, making it safe to update specific content without affecting the entire post structure.
Important: The URL must append a trailing slash to the blog post slug in the URL path (
/v2/posts/your-post-slug/). This is required for the endpoint to function correctly.
Scheduling Limitations: Blog post scheduling is not available through the Write API. Any scheduled parameters in your request will be silently ignored (not treated as errors), allowing you to safely update posts that are currently scheduled without affecting their publication timing.
Media Integration: Include upload_images_to_media_library=true in your request to automatically download and upload any image URLs within the post body to your ButterCMS media library. This ensures reliable hosting and CDN performance for your content images.
Asynchronous Processing: This endpoint returns 202 Accepted immediately to ensure fast response times for your application. The actual update processing, including media uploads, content validation, and webhook notifications, happens in the background processing queue.
Security
writeTokenAuth
The slug of the blog post.
Auto-Slugification: The API automatically converts your input to a valid slug format using unicode slugification.
Example: "updated-blog-post-slug"
The status of the post.
Note: "scheduled" status will be ignored and a warning message will be included in the response.
Enum"draft""published""scheduled"
Example: "published"
One of:
Author reference for blog posts. Author must exist in your account prior to POST.
You can specify the author either by email or by slug. If no author is specified, defaults to the organization owner.
Array of category names. Categories will be created if they don't exist.
Example: ["Updated Category","New Category"]
Array of tag names. Tags will be created if they don't exist.
Example: ["updated","refresh","api"]
Can be a remote URL to an image.
The image will always be uploaded to the media library (the value of upload_images_to_media_library is ignored for featured images).
Example: "https://example.com/updated-featured-image.jpg"
Alt text for the featured image
Example: "Updated featured image alt text."
Should be a string of escaped HTML.
In case it contains any remote URLs to images, the upload_images_to_media_library flag controls the behavior.
Example: "<h1>Updated Content</h1><p>This blog post was updated via API</p>"
Plain-text summary of the blog post
Example: "Updated summary of the blog post."
Meta description for SEO and social sharing
Example: "Updated meta description for better SEO."
Defaults to false.
If set to true, any image URLs in the body property will be uploaded to the Butter Media Library and the original URL will be replaced with the media library URL.
Note: Featured images are always uploaded regardless of this setting.
Default false
Example: true
- ButterCMS API v2
https://api.buttercms.com/v2/posts/{slug}/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PATCH \
https://api.buttercms.com/v2/posts/this-is-a-blog-post/ \
-H 'Authorization: Bearer <YOUR_Token_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"slug": "the-new-post-slug",
"body": "<h1>Updated</h1><p>This blog post was updated via API</p>"
}'Accepted - Post Update Initiated
The update request has been accepted and will be processed asynchronously. The response may include warning messages if certain fields were ignored (such as scheduling-related fields).
Warning Messages: If you provided scheduled timestamp or status: "scheduled", these will be ignored and warning messages will be included in the response.
Indicates that the blog post update is being processed asynchronously
Value"pending"
Example: "pending"
Warning message when scheduled field is ignored
Example: "Scheduled timestamps cannot be created or altered via write API. This field will be ignored."
Warning message when scheduled status is ignored
Example: "A blog post's status cannot be set as `scheduled` via write API at this time. This field will be ignored."
Response
application/json
{ "status": "pending" }
Request
Delete an existing blog post using a soft delete operation that marks the post as deleted while preserving the content for potential recovery. This approach ensures data safety while removing posts from public visibility.
Important: You must append a trailing slash to the end of the blog post slug in the URL path:
/v2/posts/your-post-slug/. This is required for the endpoint to function correctly.
Soft Delete Behavior: The post is marked as deleted in the system and will no longer appear in blog listings, search results, RSS feeds, or other public endpoints. However, the actual content and metadata are preserved in the database, allowing for potential recovery through support channels if needed.
Access Control: You can only delete blog posts that belong to your organization. Attempting to delete posts from other organizations will result in a 404 Not Found response, ensuring proper data isolation and security.
Security
writeTokenAuth
- ButterCMS API v2
https://api.buttercms.com/v2/posts/{slug}/
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
https://api.buttercms.com/v2/posts/this-is-a-blog-post/ \
-H 'Authorization: Bearer <YOUR_Token_HERE>'No Content - Blog Post Successfully Deleted
The blog post has been successfully deleted (soft delete). The response body is empty.
Note: This is a soft delete operation. The post is marked as deleted but not physically removed from the system.
Response
No contentWebhooks - 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.