Skip to content

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.

New Documentation Version

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/

API Overview

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
Languages
Servers
ButterCMS API v2

https://api.buttercms.com/v2/

Product Architecture & Integration

ButterCMS API architecture and performance characteristics for developers integrating headless CMS functionality.

Pages - Key Concepts

Essential concepts for working with ButterCMS Pages, including unique features, publication states, and architectural patterns.

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.

Collections - Key Concepts

Essential concepts for working with ButterCMS Collections, including unique characteristics, publication workflows, and architectural patterns optimized for structured data management.

Blogs - Key Concepts

Essential concepts for working with ButterCMS Blog Posts, including predefined schemas, built-in organizational features, and publication characteristics.

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 - Write

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.

Operations

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

Collections - Write

Create, update, and delete Collection items using ButterCMS Write API. Collections are user-defined content structures with completely customizable field schemas.

Operations

Collections - Read

Retrieve collection items from your ButterCMS account. Collections are flexible, user-defined content structures with completely customizable field schemas.

See also: Architecture & Performance for guidance on levels, pagination, and performance best practices.

Operations

Blog Posts - Write

Create, update, and delete blog posts using ButterCMS Write API. Blog posts support rich content including HTML body, categories, tags, featured images, and SEO metadata.

Operations

Blog Posts - Read

Retrieve blog posts from your ButterCMS account. List blog posts with pagination and filtering options, or retrieve individual posts by slug.

Operations

Blog Metadata

Retrieve blog-related metadata including authors, categories, and tags. These endpoints provide access to the organizational structure of your blog content.

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

Request

Triggered when a page is published or republished.

This event fires when:

  • A draft page is published for the first time
  • An already published page is republished after changes
  • A scheduled page is automatically published
Bodyapplication/jsonrequired
dataobject(PageWebhookData)

Webhook data payload for page events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "product-launch", "buttercms_id": 5678, "page_type": "landing", "editor": "Marketing Team", "name": "Product Launch Landing Page", "timestamp": "2024-01-15T14:30:00", "locale": null, "status": "published", "updated": "2024-01-15T14:30:00.123456Z", "published": "2024-01-15T14:30:00.123456Z", "scheduled": null }, "webhook": { "event": "page.published", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a draft page version is saved.

This event fires when:

  • A new page is created and saved as draft
  • An existing draft page is updated and saved
  • A published page is updated but not yet republished
Bodyapplication/jsonrequired
dataobject(PageWebhookData)

Webhook data payload for page events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "upcoming-event", "buttercms_id": 9012, "page_type": "event", "editor": "Event Coordinator", "name": "Upcoming Conference Event", "timestamp": "2024-01-15T16:45:00", "locale": "en", "status": "draft", "updated": "2024-01-15T16:45:00.987654Z", "published": null, "scheduled": "2024-02-01T09:00:00.000000Z" }, "webhook": { "event": "page.draft", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a published page is unpublished (but not deleted).

This event fires when:

  • A published page is deliberately unpublished but kept in the system
  • A page is temporarily taken offline without permanent deletion
Bodyapplication/jsonrequired
dataobject(PageWebhookData)

Webhook data payload for page events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "maintenance-notice", "buttercms_id": 7890, "page_type": "notice", "editor": "Site Administrator", "name": "Maintenance Notice", "timestamp": "2024-01-15T22:00:00", "locale": null, "status": "draft", "updated": "2024-01-15T22:00:00.333444Z", "published": null, "scheduled": null }, "webhook": { "event": "page.unpublished", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a published page is permanently deleted.

This event fires when:

  • A page is permanently removed from the system
  • A page is moved to trash and then permanently deleted
Bodyapplication/jsonrequired
dataobject(PageWebhookData)

Webhook data payload for page events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "old-promotion", "buttercms_id": 3456, "page_type": "promo", "editor": "Content Manager", "name": "Old Promotion Page", "timestamp": "2024-01-15T20:15:00", "locale": null, "status": "deleted", "updated": "2024-01-15T20:15:00.111222Z", "published": "2024-01-10T10:00:00.000000Z", "scheduled": null }, "webhook": { "event": "page.delete", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when any activity occurs on a page (create, update, publish, unpublish, delete).

This is a catch-all event that fires for all page changes, useful for comprehensive page monitoring and cache invalidation across all page types.

Bodyapplication/jsonrequired
dataobject(PageWebhookData)

Webhook data payload for page events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "company-news", "buttercms_id": 1234, "page_type": "news", "editor": "Jane Editor", "name": "Company News Page", "timestamp": "2024-01-15T18:11:09", "locale": "en", "status": "published", "updated": "2024-01-15T18:11:09.791061Z", "published": "2024-01-15T18:10:00.000000Z", "scheduled": null }, "webhook": { "event": "page.all", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a blog post is published or republished.

This event fires when:

  • A draft blog post is published for the first time
  • An already published post is republished after changes
  • A scheduled post is automatically published
Bodyapplication/jsonrequired
dataobject(BlogPostWebhookData)

Webhook data payload for blog post events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "announcing-new-features", "_id": 5678 }, "webhook": { "event": "post.published", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a draft blog post is saved.

This event fires when:

  • A new blog post is created and saved as draft
  • An existing draft is updated and saved
  • A published post is updated and saved as draft (effectively unpublishing)
Bodyapplication/jsonrequired
dataobject(BlogPostWebhookData)

Webhook data payload for blog post events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "work-in-progress-post", "_id": 9012 }, "webhook": { "event": "post.draft", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a published blog post is unpublished or deleted.

This event fires when:

  • A published blog post is moved to trash
  • A published blog post is permanently deleted
  • A published blog post is unpublished (soft delete)
Bodyapplication/jsonrequired
dataobject(BlogPostWebhookData)

Webhook data payload for blog post events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "outdated-announcement", "_id": 3456 }, "webhook": { "event": "post.delete", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when any activity occurs on a blog post (create, update, publish, unpublish, delete).

This is a catch-all event that fires for all blog post changes, making it useful for general blog post monitoring and cache invalidation.

Bodyapplication/jsonrequired
dataobject(BlogPostWebhookData)

Webhook data payload for blog post events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "api-development-best-practices", "_id": 1234 }, "webhook": { "event": "post.all", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Collection Item - PublishedWebhook

Request

Triggered when a collection item is published or republished.

This event fires when:

  • A draft collection item is published for the first time
  • An already published item is republished after changes
  • A scheduled item is automatically published
Bodyapplication/jsonrequired
dataobject(CollectionItemWebhookData)

Webhook data payload for collection item events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "products", "itemid": "/v2/content/?keys=products[_id=5678]", "label": "Wireless Headphones Pro", "editor": "Product Manager", "timestamp": "2024-01-15T13:45:00", "locale": null, "status": "published" }, "webhook": { "event": "collectionitem.published", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Collection Item - Draft SavedWebhook

Request

Triggered when a collection item draft is saved.

This event fires when:

  • A new collection item is created and saved as draft
  • An existing draft item is updated and saved
  • A published item is updated but not yet republished
Bodyapplication/jsonrequired
dataobject(CollectionItemWebhookData)

Webhook data payload for collection item events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "events", "itemid": "/v2/content/?keys=events[_id=9012]", "label": "Annual Developer Conference 2024", "editor": "Event Planner", "timestamp": "2024-01-15T15:20:00", "locale": "en", "status": "draft" }, "webhook": { "event": "collectionitem.draft", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Collection Item - UnpublishedWebhook

Request

Triggered when a collection item is unpublished (but not deleted).

This event fires when:

  • A published collection item is deliberately unpublished but kept in the system
  • An item is temporarily taken offline without permanent deletion
Bodyapplication/jsonrequired
dataobject(CollectionItemWebhookData)

Webhook data payload for collection item events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "promotions", "itemid": "/v2/content/?keys=promotions[_id=7890]", "label": "Holiday Sale 2023", "editor": "Marketing Manager", "timestamp": "2024-01-15T21:00:00", "locale": "en", "status": "draft" }, "webhook": { "event": "collectionitem.unpublished", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a collection item is deleted.

This event fires when:

  • A collection item is permanently removed from the system
  • A collection item is moved to trash and then permanently deleted
Bodyapplication/jsonrequired
dataobject(CollectionItemWebhookData)

Webhook data payload for collection item events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "testimonials", "itemid": "/v2/content/?keys=testimonials[_id=3456]", "label": "Customer Review - ABC Corp", "editor": "Content Moderator", "timestamp": "2024-01-15T19:30:00", "locale": null, "status": "deleted" }, "webhook": { "event": "collectionitem.delete", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Collection Item - Any ActivityWebhook

Request

Triggered when any activity occurs on a collection item (create, update, publish, unpublish, delete).

This is a catch-all event that fires for all collection item changes, useful for comprehensive content monitoring across all collections.

Bodyapplication/jsonrequired
dataobject(CollectionItemWebhookData)

Webhook data payload for collection item events

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "team_members", "itemid": "/v2/content/?keys=team_members[_id=1234]", "label": "John Smith - Senior Developer", "editor": "HR Manager", "timestamp": "2024-01-15T11:30:00", "locale": "en", "status": "published" }, "webhook": { "event": "collectionitem.all", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

Request

Triggered when a video file is uploaded to the media library.

This event fires when:

  • A new video file is uploaded to ButterCMS media library
  • Video processing is completed and the file is available
Bodyapplication/jsonrequired
dataobject

Video upload event data (structure may vary)

webhookobject

Webhook metadata included in all webhook payloads

application/json
{ "data": { "id": "promotional-video-2024", "media_id": 12345, "filename": "company-promo.mp4", "size": 52428800, "url": "https://cdn.buttercms.com/video/company-promo.mp4" }, "webhook": { "event": "media.videouploaded", "target": "https://yourapp.com/webhooks/buttercms" } }

Responses

Return a 200 status to indicate that the data was received successfully

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.