Skip to content
Blog Posts - Read

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
index.json
index.yaml
Overview
E-mail

support@buttercms.com

License

ButterCMS Terms of Service

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

List All Posts

Request

Retrieve a paginated list of all published blog posts, automatically sorted by publication date with the newest posts appearing first. This endpoint is ideal for building blog listing pages, RSS feeds, or content archives.

Performance Optimization: Use the exclude_body=true parameter when building post listing pages to significantly reduce response size by excluding the full post content. This improves loading performance while still providing titles, summaries, metadata, and author information needed for listing displays.

Security
readTokenAuth
Query
pageinteger>= 1

Page number for page-based pagination.

Mutually exclusive with limit/offset parameters.

Default 1
Example: page=2
page_sizeinteger[ 1 .. 100 ]

Number of items per page for page-based pagination.

Mutually exclusive with limit/offset parameters.

Default 10
Example: page_size=5
limitinteger[ 1 .. 100 ]

Maximum number of items to return for offset-based pagination.

Mutually exclusive with page/page_size parameters.

Default 10
Example: limit=5
offsetinteger>= 0

Number of items to skip before starting to return results.

Mutually exclusive with page/page_size parameters.

Default 0
Example: offset=10
previewinteger

Set to 1 to return the latest draft version of a page. Useful for previewing changes before publishing live. i.e. &preview=1. If you are trying to view a scheduled page for which the most recent page version is published, you must pass the preview parameter to see the scheduled changes.

Set to 1 to access unpublished/draft collection items. Useful for staging environments.

Default 0
Enum01
Example: preview=1
exclude_bodyboolean

When true, excludes the full post body from the response.

Performance benefit: Significantly reduces response size when displaying lists of blog posts.

Default false
Example: exclude_body=true
author_slugstring

Filter posts by an author's slug.

Example: author_slug=api-test
category_slugstring

Filter posts by a category's slug.

Example: category_slug=test-category
tag_slugstring

Filter posts by a tag's slug.

Example: tag_slug=test-tag
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
curl -i -X GET \
  'https://api.buttercms.com/v2/posts/?page=2&page_size=5&limit=5&offset=10&preview=1&exclude_body=true&author_slug=api-test&category_slug=test-category&tag_slug=test-tag&auth_token=your_api_token%2CYOUR_API_KEY_HERE'

Responses

Success - Blog Posts Retrieved

Returns a list of blog posts matching the specified criteria. Posts are sorted by publish date with the most recent posts first.

Bodyapplication/json
One of:

Blog posts response using page-based pagination (default)

metaobject(PaginationMeta)required
meta.​previous_pageinteger or null

Previous page number if it exists

meta.​next_pageinteger or null

Next page number if it exists

meta.​countinteger

Total number of items

dataArray of objects(BlogPostObject)required

Array of blog post objects sorted by publish date (newest first)

data[].​urlstring(uri)

Full URL to the blog post

Example: "http://www.example.com/blog/this-is-a-blog-post"
data[].​createdstring(date-time)

Timestamp when the blog post was created

Example: "2020-10-08T18:29:19.987936Z"
data[].​updatedstring(date-time)

Timestamp when the blog post was last updated

Example: "2020-10-09T15:49:54.580309Z"
data[].​publishedstring or null(date-time)

Timestamp when the blog post was published

Example: "2020-10-08T18:08:00Z"
data[].​authorobject(BlogPostAuthorObject)

Author information for blog posts

data[].​categoriesArray of objects(CategoryObject)

Array of categories assigned to the blog post

data[].​tagsArray of objects(TagObject)

Array of tags assigned to the blog post

data[].​featured_imagestring or null(uri)

URL to the featured image, null if no featured image

Example: null
data[].​featured_image_altstring

Alt text for the featured image

Example: ""
data[].​slugstring

URL-friendly slug for the blog post

Example: "this-is-a-blog-post"
data[].​titlestring

Title of the blog post

Example: "This is a blog post"
data[].​bodystring

HTML content body of the blog post (excluded if exclude_body=true)

Example: "<p class=\"\">This is a blog post to test the API.</p>"
data[].​summarystring

Plain text summary of the blog post

Example: "This is a blog post to test the API."
data[].​seo_titlestring

SEO-optimized title for the blog post

Example: "This is a blog post"
data[].​meta_descriptionstring

Meta description for SEO and social sharing

Example: "This is a blog post to test the API."
data[].​statusstring

Publication status of the blog post

Enum"draft""published""scheduled"
Example: "published"
data[].​scheduledstring or null(date-time)

Timestamp when the blog post is scheduled to be published. If not scheduled, this field will be null

Example: null
Response
application/json

Using ?page=2&page_size=5 parameters

{
  "meta": {
    "count": 25,
    "next_page": 3,
    "previous_page": 1
  },
  "data": [
    { … }
  ]
}

Retrieve Single Post

Request

Retrieve a specific blog post by its unique slug, including complete post content, metadata, and navigation information. This endpoint is ideal for building individual blog post pages with full content display.

Universal Access: This endpoint retrieves posts regardless of their publication status (published, draft, or scheduled), making it perfect for preview functionality and content management workflows. Note that draft and scheduled posts won't appear in listing endpoints unless preview mode is specifically enabled.

Navigation Support: The response includes a helpful meta object containing next_post and previous_post navigation links, allowing you to easily implement "Previous/Next" navigation on your blog post pages without additional API calls.

Important: You must append a trailing slash to the URL path: /v2/posts/your-post-slug/. This is required for the endpoint to function correctly.

Security
readTokenAuth
Path
slugstring<= 100 charactersrequired

The unique slug of the blog post to retrieve.

Important: The URL must end with a trailing slash (/v2/posts/your-slug/).

Example: hello-world
Query
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
curl -i -X GET \
  'https://api.buttercms.com/v2/posts/hello-world/?auth_token=your_api_token%2CYOUR_API_KEY_HERE'

Responses

Success - Blog Post Retrieved

Returns the complete blog post object along with navigation metadata for browsing between posts.

Bodyapplication/json
metaobject(SinglePostMeta)

Navigation metadata for single blog post responses

dataobject(BlogPostObject)

Complete blog post object with all fields and related data

Response
application/json
{
  "meta": {
    "next_post": null,
    "previous_post": { … }
  },
  "data": {
    "url": "http://www.example.com/blog/hello-world",
    "created": "2015-06-12T13:59:32.441289Z",
    "published": "2015-06-12T00:00:00Z",
    "author": { … },
    "categories": [ … ],
    "tags": [ … ],
    "featured_image": null,
    "featured_image_alt": "",
    "slug": "hello-world",
    "title": "This is a blog post",
    "body": "<p class=\"\">This is a blog post to test the API.</p>",
    "summary": "This is a blog post to test the API.",
    "seo_title": "This is a blog post",
    "meta_description": "This is a blog post to test the API.",
    "status": "published"
  }
}

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

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.