Skip to main content

​
Base URL

https://api.buttercms.com/v2
All API requests must be made over HTTPS. Requests made over plain HTTP will fail.

​
Endpoint overview

​
Pages endpoints

MethodEndpointDescription
GET/pages/List all Single Pages
GET/pages/{page_type}/List pages of a specific Page Type
GET/pages/{page_type}/{page_slug}/Retrieve a specific page by slug
GET/pages/search/Search pages by query string (?query=term)
POST/pages/Create a new page
PUT/pages/*/{page_slug}/Update an existing page
PATCH/pages/*/{page_slug}/Partially update a page
DELETE/pages/*/{page_slug}/Delete a page

​
Collections endpoints

MethodEndpointDescription
GET/content/List all Collections
GET/content/{collection_key}/Retrieve items from a Collection
GET/content/{collection_key}/{item_id}/Retrieve a specific Collection item
POST/content/Create a new Collection item
PUT/content/{collection_key}/{item_id}/Update a Collection item
PATCH/content/{collection_key}/{item_id}/Partially update a Collection item
DELETE/content/{collection_key}/{item_id}/Delete a Collection item

​
Blog Posts endpoints

MethodEndpointDescription
GET/posts/List all blog posts
GET/posts/{slug}/Retrieve a specific blog post
GET/posts/search/Search blog posts
POST/posts/Create a new blog post
PUT/posts/{slug}/Update a blog post
PATCH/posts/{slug}/Partially update a blog post
DELETE/posts/{slug}/Delete a blog post

​
Blog metadata endpoints

MethodEndpointDescription
GET/authors/List all authors
GET/authors/{slug}/Retrieve a specific author
GET/categories/List all categories
GET/categories/{slug}/Retrieve a specific category
GET/tags/List all tags
GET/tags/{slug}/Retrieve a specific tag

​
Feeds endpoints

MethodEndpointDescription
GET/feeds/rss/RSS feed of blog posts
GET/feeds/atom/Atom feed of blog posts
GET/feeds/sitemap/XML sitemap

​
URL structure

​
Pages URL pattern

/pages/{page_type}/{page_slug}/
Parameters:
  • page_type: The slug of the Page Type (use * for Single Pages)
  • page_slug: The unique slug identifier of the page
Examples: 
# Get a Single Page
GET /pages/*/homepage/

# Get a page from a Page Type
GET /pages/landing-pages/summer-sale/

# List all pages of a type
GET /pages/blog-posts/

​
Collections URL pattern

/content/{collection_key}/
/content/{collection_key}/{item_id}/
Parameters:
  • collection_key: The unique identifier/slug of the Collection
  • item_id: The numeric ID of the Collection item
Examples: 
# Get all items from a Collection
GET /content/artists/

# Get a specific Collection item
GET /content/artists/123/

​
Blog Posts URL pattern

/posts/{slug}/
Parameters:
  • slug: The unique slug identifier of the blog post
Examples: 
# List all posts
GET /posts/

# Get a specific post
GET /posts/hello-world/

# Search posts
GET /posts/search/?query=butter

​
Common query parameters

​
Authentication

ParameterDescription
auth_tokenYour Read API token (alternative to Authorization header)

​
Pagination

ParameterDescriptionDefault
pagePage number for page-based pagination1
page_sizeNumber of items per page10
limitNumber of items to return (offset pagination)-
offsetNumber of items to skip (offset pagination)0
orderSort order (-field for descending, field for ascending)-

​
Content options

ParameterDescriptionDefault
previewInclude draft content (1 = enabled)0
localeLocale code for localized content (e.g., en, es)Default locale
levelsDepth of reference field resolution (1-5)2

​
Blog-specific

ParameterDescription
exclude_bodyExclude post body for faster list responses (true/false)
category_slugFilter posts by category
tag_slugFilter posts by tag
author_slugFilter posts by author

​
Example API calls

​
Fetching Pages

# List all pages of a Page Type with pagination
curl "https://api.buttercms.com/v2/pages/landing-pages/?auth_token=YOUR_TOKEN&page=1&page_size=10"

# Get a specific page with full reference resolution
curl "https://api.buttercms.com/v2/pages/landing-pages/summer-sale/?auth_token=YOUR_TOKEN&levels=3"

# Get a page in Spanish locale
curl "https://api.buttercms.com/v2/pages/landing-pages/summer-sale/?auth_token=YOUR_TOKEN&locale=es"

# Preview a draft page
curl "https://api.buttercms.com/v2/pages/landing-pages/summer-sale/?auth_token=YOUR_TOKEN&preview=1"

​
Fetching Collections

# Get all items from a Collection
curl "https://api.buttercms.com/v2/content/artists/?auth_token=YOUR_TOKEN"

# Filter Collection by field value
curl "https://api.buttercms.com/v2/content/artists/?auth_token=YOUR_TOKEN&fields.genre=Rock"

# Get a specific Collection item
curl "https://api.buttercms.com/v2/content/artists/123/?auth_token=YOUR_TOKEN"

# Paginated Collection with ordering
curl "https://api.buttercms.com/v2/content/artists/?auth_token=YOUR_TOKEN&page=2&page_size=20&order=-name"

​
Fetching Blog Posts

# List all published posts
curl "https://api.buttercms.com/v2/posts/?auth_token=YOUR_TOKEN"

# Get posts without body content (faster)
curl "https://api.buttercms.com/v2/posts/?auth_token=YOUR_TOKEN&exclude_body=true"

# Filter posts by category
curl "https://api.buttercms.com/v2/posts/?auth_token=YOUR_TOKEN&category_slug=technology"

# Search posts
curl "https://api.buttercms.com/v2/posts/search/?auth_token=YOUR_TOKEN&query=headless%20cms"

# Get a single post with next/previous navigation
curl "https://api.buttercms.com/v2/posts/hello-world/?auth_token=YOUR_TOKEN"

​
Trailing slashes

ButterCMS API endpoints require trailing slashes. Requests without trailing slashes will be redirected.
# Correct
GET /posts/

# Incorrect (will redirect)
GET /posts

​
HTTPS required

All API requests must use HTTPS. The API does not accept plain HTTP requests. 
# Correct
https://api.buttercms.com/v2/posts/

# Incorrect
http://api.buttercms.com/v2/posts/

​
Next steps

Request/Response Format

Learn about JSON data structures

HTTP Status Codes

Understand error responses