Skip to content
/
List All Authors

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

Blog Metadata

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

Operations

List All Authors

Request

Retrieve a complete list of all blog post authors in your organization, including their profile information and optional recent post data. This endpoint is ideal for building author pages, contributor listings, and author-based navigation.

Author Profiles: Returns comprehensive profile information for each author, including personal details like name and bio, social media profiles, profile images, and author metadata. This provides everything needed to build rich author profile pages.

Recent Posts Integration: Use the include=recent_posts parameter to enrich the response with each author's most recent blog posts. This is particularly useful for creating author archive pages that showcase both the author's profile and their latest content contributions.

Security
readTokenAuth
Query
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
includestring

Include additional data in the response.

When set to recent_posts, each author object will include a recent_posts array containing their latest blog posts.

Value"recent_posts"
Example: include=recent_posts
curl -i -X GET \
  'https://api.buttercms.com/v2/authors/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&include=recent_posts'

Responses

Authors retrieved successfully

Bodyapplication/json
dataArray of objects(AuthorObject)

Array of author objects

Response
application/json
{
  "data": [
    { … },
    { … }
  ]
}

Retrieve Author

Request

Retrieve detailed information about a specific author by their unique slug identifier, including complete profile data and optional recent posts integration.

Author Profile Information: Returns comprehensive author profile including personal details (name, email, bio, title), complete social media profiles (LinkedIn, Facebook, Pinterest, Instagram, Twitter), profile image CDN URL, and unique slug identifier for URL-friendly referencing.

Recent Posts Integration: Use the include=recent_posts parameter to enrich the response with the author's most recent blog posts. This is particularly useful for creating detailed author profile pages that showcase both their biography and latest content contributions.

Security
readTokenAuth
Path
slugstring<= 100 charactersrequired

The unique slug identifier of the author to retrieve.

Must match an existing author slug in your organization.

Example: jennifer-smith
Query
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
includestring

Include additional data in the response.

When set to recent_posts, the author object will include a recent_posts array containing their latest blog posts.

Value"recent_posts"
Example: include=recent_posts
curl -i -X GET \
  'https://api.buttercms.com/v2/authors/jennifer-smith/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&include=recent_posts'

Responses

Author retrieved successfully

Bodyapplication/json
dataobject(AuthorObject)

Single author object

Response
application/json
{
  "data": {
    "slug": "jennifer-smith",
    "first_name": "Jennifer",
    "last_name": "Smith",
    "email": "jennifersmith@buttercms.com",
    "bio": "I love coffee!",
    "title": "President",
    "linkedin_url": "https://www.linkedin.com/in/jennifersmith",
    "facebook_url": "https://www.facebook.com/jennifersmith",
    "pinterest_url": "https://www.pinterest.com/jennifersmith",
    "instagram_url": "https://www.instagram.com/jennifersmith",
    "twitter_handle": "jennifersmith",
    "profile_image": "https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ.png"
  }
}

List All Categories

Request

Retrieve a complete list of all blog post categories in your organization, including category information and optional recent post data. This endpoint is perfect for building category navigation, content organization systems, and category-based filtering interfaces.

Category Information: Returns the category name and URL-friendly slug for each category that contains published posts. This provides the essential data needed for building category-based navigation and filtering systems on your blog.

Recent Posts Integration: Use the include=recent_posts parameter to enrich the response with each category's most recent blog posts. This is ideal for creating category landing pages that display both the category information and a preview of the latest content within that category.

Security
readTokenAuth
Query
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
includestring

Include additional data in the response.

When set to recent_posts, each category object will include a recent_posts array containing the latest blog posts in that category.

Value"recent_posts"
Example: include=recent_posts
curl -i -X GET \
  'https://api.buttercms.com/v2/categories/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&include=recent_posts'

Responses

Categories retrieved successfully

Bodyapplication/json
dataArray of objects(CategoryObjectWithPosts)

Array of category objects

Response
application/json
{
  "data": [
    { … },
    { … },
    { … },
    { … }
  ]
}

Retrieve Category

Request

Retrieve a specific blog post category by its unique slug identifier, providing category information and optional recent posts integration. Categories help organize blog content into logical topical groups for improved navigation and content discovery.

Category Information: The category object contains the display name (e.g., "Product Updates") and URL-friendly slug identifier (e.g., "product-updates") that can be used for building category-based navigation and content organization systems.

Recent Posts Integration: Use the include=recent_posts parameter to enrich the response with the category's recent blog posts. This adds a recent_posts array containing up to 10 of the most recently published posts in this category, ideal for creating category landing pages that showcase both the category information and latest content.

Security
readTokenAuth
Path
slugstringrequired

The unique slug identifier of the category to retrieve.

Example: product-updates
Query
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
includestring

Include additional data in the response.

When set to recent_posts, the category object will include a recent_posts array containing the latest blog posts in this category (up to 10 posts, ordered by most recent first).

Value"recent_posts"
Example: include=recent_posts
curl -i -X GET \
  'https://api.buttercms.com/v2/categories/product-updates/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&include=recent_posts'

Responses

Category retrieved successfully

Bodyapplication/json
dataobject(CategoryObjectWithPosts)

Single category object

Response
application/json
{
  "data": {
    "name": "Product Updates",
    "slug": "product-updates"
  }
}

List All Tags

Request

Retrieve a complete list of all blog post tags in your organization, providing granular categorization and labeling information for your blog content. This endpoint is essential for building tag-based navigation, content discovery features, and detailed content organization systems.

Tag Information: Returns the tag name and URL-friendly slug for each tag that contains published posts. Tags offer more granular content categorization than categories, allowing for detailed topical organization and improved content discoverability.

Recent Posts Integration: Use the include=recent_posts parameter to enrich the response with each tag's most recent blog posts. This is particularly useful for creating tag cloud interfaces, topic-based landing pages, and tag archive pages that showcase recent activity for specific topics.

Security
readTokenAuth
Query
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
includestring

Include additional data in the response.

When set to recent_posts, each tag object will include a recent_posts array containing the latest blog posts tagged with that tag.

Value"recent_posts"
Example: include=recent_posts
curl -i -X GET \
  'https://api.buttercms.com/v2/tags/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&include=recent_posts'

Responses

Tags retrieved successfully

Bodyapplication/json
dataArray of objects(TagObjectWithPosts)

Array of tag objects

Response
application/json
{
  "data": [
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}

Retrieve Tag

Request

Retrieve a specific blog post tag by its unique slug identifier, providing detailed tag information and optional recent posts integration. Tags provide granular categorization and labeling for blog content, enabling detailed content organization and enhanced discovery capabilities.

Tag Information: The tag object contains the display name (e.g., "API Development") and URL-friendly slug identifier (e.g., "api-development") that can be used for building tag-based navigation, content filtering, and topic-specific landing pages.

Recent Posts Integration: Use the include=recent_posts parameter to enrich the response with the tag's recent blog posts. This adds a recent_posts array containing up to 10 of the most recently published posts tagged with this tag, perfect for creating comprehensive tag pages that showcase both tag information and the latest related content.

Security
readTokenAuth
Path
slugstringrequired

The unique slug identifier of the tag to retrieve.

Example: api-development
Query
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
includestring

Include additional data in the response.

When set to recent_posts, the tag object will include a recent_posts array containing the latest blog posts tagged with this tag (up to 10 posts, ordered by most recent first).

Value"recent_posts"
Example: include=recent_posts
curl -i -X GET \
  'https://api.buttercms.com/v2/tags/api-development/?auth_token=your_api_token%2CYOUR_API_KEY_HERE&include=recent_posts'

Responses

Tag retrieved successfully

Bodyapplication/json
dataobject(TagObjectWithPosts)

Single tag object

Response
application/json
{
  "data": {
    "name": "API Development",
    "slug": "api-development"
  }
}

Search Posts

Request

Search blog posts using advanced full-text search capabilities across titles and content, with intelligent relevance scoring to surface the most relevant results first.

Search Algorithm: The search engine performs comprehensive full-text indexing across post titles, body content, and summary fields using natural language processing. Results are ranked by relevance score, taking into account factors like keyword frequency, title matches, content quality signals, and publication recency.

Content Scope: The search indexes all published post content including titles, body text, summary fields, and associated metadata. Draft and scheduled posts are excluded from search results unless you're using preview mode through other endpoints.

Result Optimization: Returns complete post objects with calculated relevance scores by default. Use the exclude_body=true parameter when building search result pages to significantly reduce response size and improve loading performance, particularly for mobile applications.

Performance Features: Search results are automatically cached to ensure fast response times for repeated queries. The search index is updated in real-time as content is published, ensuring fresh results without manual reindexing.

Security
readTokenAuth
Query
querystring<= 100 characters

Search query string to find matching blog posts.

The search will look for matches in both post titles and body content. Uses natural language processing for best results. If empty or not provided, no results will be returned.

Default ""
Example: query=API development best practices
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
exclude_bodyboolean

Exclude the full blog post body content from results to reduce response size.

When set to true, the response will omit the body field from each post object, making responses faster and lighter for cases where only post metadata is needed.

Default false
auth_tokenstringrequired

Your ButterCMS read API token

Example: auth_token=your_api_token
curl -i -X GET \
  'https://api.buttercms.com/v2/posts/search/?query=API+development+best+practices&page=2&page_size=5&limit=5&offset=10&exclude_body=false&auth_token=your_api_token%2CYOUR_API_KEY_HERE'

Responses

Search completed successfully

Bodyapplication/json
One of:

Blog post search response using page-based pagination

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(BlogPostSearchResult)required

Array of blog post search results with relevance ranking

data[].​urlstring(uri)

Full URL to the blog post

Example: "https://api.buttercms.com/blog/api-development-best-practices"
data[].​createdstring(date-time)

Creation date and time in ISO 8601 format

Example: "2024-01-15T08:30:00.000Z"
data[].​publishedstring(date-time)

Publication date and time in ISO 8601 format

Example: "2024-01-15T10:00:00.000Z"
data[].​authorobject(BlogPostAuthorObject)

Author information

data[].​categoriesArray of objects(CategoryObject)

Array of category objects

data[].​tagsArray of objects(TagObject)

Array of tag objects

data[].​featured_imagestring or null(uri)

CDN URL of the featured image, null if no image

Example: "https://cdn.buttercms.com/featured/api-guide.jpg"
data[].​featured_image_altstring

Alt text for the featured image

Example: "API Development Guide"
data[].​slugstring

URL-friendly slug identifier

Example: "api-development-best-practices"
data[].​titlestring

Blog post title

Example: "API Development Best Practices for 2024"
data[].​bodystring

Full HTML content of the blog post (excluded when exclude_body=true)

Example: "<h2>Introduction</h2><p>Building robust APIs requires following established best practices...</p>"
data[].​summarystring

Summary or excerpt of the blog post

Example: "Learn the essential best practices for building scalable and maintainable APIs in 2024."
data[].​seo_titlestring

SEO-optimized title

Example: "API Development Best Practices for 2024"
data[].​meta_descriptionstring

Meta description for SEO

Example: "Complete guide to API development best practices including REST design, authentication, and documentation."
data[].​statusstring

Publication status (only published posts appear in search results)

Value"published"
Example: "published"
data[].​ranknumber(float)[ 0 .. 1 ]

Search relevance score (higher values indicate better matches)

Example: 0.8573
Response
application/json
{
  "meta": {
    "count": 2,
    "next_page": null,
    "previous_page": null
  },
  "data": [
    { … },
    { … }
  ]
}

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.