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.
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.
Generate a fully compliant RSS 2.0 XML feed for your blog content, perfect for syndication, feed readers, and content distribution. This endpoint automatically formats your blog posts into the standard RSS format with optional filtering capabilities.
RSS 2.0 Compliance: Produces a standards-compliant RSS 2.0 XML feed that works with all major feed readers, news aggregators, and syndication services. The feed includes post titles, descriptions, publication dates, and permalinks.
Filtering Options: Apply category or tag filters to create specialized feeds for specific content topics. This allows you to offer targeted RSS feeds for different audience segments or content verticals.
https://api.buttercms.com/v2/feeds/rss/
curl -i -X GET \
'https://api.buttercms.com/v2/feeds/rss/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&category_slug=announcements&tag_slug=product-updates'
<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
<channel>
<title>Latest blog posts</title>
<link>https://example.buttercms.com/blog/rss/</link>
<description />
<atom:link href="https://example.buttercms.com/blog/rss/" rel="self" />
<language>en-us</language>
<lastBuildDate>Mon, 15 Jan 2024 10:00:00 +0000</lastBuildDate>
<item>
<title>API Development Best Practices for 2024</title>
<link>https://example.buttercms.com/blog/api-development-best-practices</link>
<media:content medium="image" url="https://cdn.buttercms.com/featured/api-guide.jpg"/>
<dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/">John Developer</dc:creator>
<pubDate>Mon, 15 Jan 2024 10:00:00 +0000</pubDate>
<guid>https://example.buttercms.com/blog/api-development-best-practices</guid>
<description>Learn the essential best practices for building scalable and maintainable APIs in 2024.</description>
<content:encoded>
<![CDATA[<h2>Introduction</h2><p>Building robust APIs requires following established best practices. In this comprehensive guide, we'll explore the key principles that ensure your APIs are scalable, maintainable, and developer-friendly.</p><h3>Key Principles</h3><p>Modern API development focuses on consistency, documentation, and performance optimization...</p>]]>
</content:encoded>
</item>
<item>
<title>RESTful API Design Principles</title>
<link>https://example.buttercms.com/blog/restful-api-design-principles</link>
<media:content medium="image" url="https://cdn.buttercms.com/featured/rest-design.jpg"/>
<dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/">Sarah Architect</dc:creator>
<pubDate>Fri, 12 Jan 2024 09:00:00 +0000</pubDate>
<guid>https://example.buttercms.com/blog/restful-api-design-principles</guid>
<description>Master the fundamental principles of RESTful API design for better developer experience.</description>
<content:encoded>
<![CDATA[<h2>Core Principles</h2><p>RESTful API design follows key principles that ensure scalability and intuitive usage. Understanding these principles is crucial for creating APIs that developers love to use.</p>]]>
</content:encoded>
</item>
</channel>
</rss>
Generate a fully compliant Atom 1.0 XML feed for your blog content, offering an alternative syndication format with rich metadata support. This endpoint is ideal for feed readers that prefer the Atom standard and applications requiring detailed content metadata.
Atom 1.0 Compliance: Produces a standards-compliant Atom 1.0 XML feed with enhanced metadata support compared to RSS. The feed includes detailed author information, updated timestamps, content types, and rich linking relationships.
Filtering Capabilities: Apply category or tag filters to generate specialized Atom feeds for specific content topics. This enables you to provide targeted content syndication for different audiences or subject areas.
https://api.buttercms.com/v2/feeds/atom/
curl -i -X GET \
'https://api.buttercms.com/v2/feeds/atom/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&category_slug=announcements&tag_slug=product-updates'
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en-us">
<title>Latest blog posts</title>
<link href="https://example.buttercms.com/blog/rss/" rel="alternate" />
<link href="https://example.buttercms.com/blog/atom/" rel="self" />
<id>https://example.buttercms.com/blog/rss/</id>
<updated>2024-01-15T10:00:00Z</updated>
<entry>
<title>API Development Best Practices for 2024</title>
<link href="https://example.buttercms.com/blog/api-development-best-practices" rel="alternate" />
<published>2024-01-15T10:00:00Z</published>
<updated>2024-01-15T10:00:00Z</updated>
<author>
<name>John Developer</name>
</author>
<id>https://example.buttercms.com/blog/api-development-best-practices</id>
<summary type="html">Learn the essential best practices for building scalable and maintainable APIs in 2024.</summary>
</entry>
<entry>
<title>RESTful API Design Principles</title>
<link href="https://example.buttercms.com/blog/restful-api-design-principles" rel="alternate" />
<published>2024-01-12T09:00:00Z</published>
<updated>2024-01-12T09:00:00Z</updated>
<author>
<name>Sarah Architect</name>
</author>
<id>https://example.buttercms.com/blog/restful-api-design-principles</id>
<summary type="html">Master the fundamental principles of RESTful API design for better developer experience.</summary>
</entry>
</feed>
Generate a comprehensive XML sitemap for your blog posts, optimized for search engine discovery and indexing. This endpoint creates a standards-compliant sitemap that helps search engines efficiently crawl and index your blog content.
SEO Optimization: Produces an XML sitemap following the sitemaps.org protocol that includes post URLs, last modification dates, and change frequency information. This helps search engines understand your content structure and prioritize crawling of updated content.
Filtering for Focused Sitemaps: Apply category or tag filters to create specialized sitemaps for specific content sections. This is useful for large blogs where you want to submit targeted sitemaps to search engines or create separate indexing strategies for different content types.
https://api.buttercms.com/v2/feeds/sitemap/
curl -i -X GET \
'https://api.buttercms.com/v2/feeds/sitemap/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&category_slug=announcements&tag_slug=seo-tips'
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">
<url>
<loc>https://example.buttercms.com/blog/api-development-best-practices</loc>
<lastmod>2024-01-15</lastmod>
</url>
<url>
<loc>https://example.buttercms.com/blog/restful-api-design-principles</loc>
<lastmod>2024-01-12</lastmod>
</url>
<url>
<loc>https://example.buttercms.com/blog/microservices-architecture-guide</loc>
<lastmod>2024-01-10</lastmod>
</url>
<url>
<loc>https://example.buttercms.com/blog/database-optimization-techniques</loc>
<lastmod>2024-01-08</lastmod>
</url>
</urlset>
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.