REST endpoints & URLs

All ButterCMS REST endpoints for Pages, Collections, Blog Posts, Authors, Categories, Tags, and Feeds, with common query parameters.

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

Method	Endpoint	Description
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

Method	Endpoint	Description
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

Method	Endpoint	Description
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

Method	Endpoint	Description
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

Method	Endpoint	Description
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

Parameter	Description
auth_token	Your Read API token (alternative to Authorization header)

Pagination

Parameter	Description	Default
page	Page number for page-based pagination	1
page_size	Number of items per page	10
limit	Number of items to return (offset pagination)	-
offset	Number of items to skip (offset pagination)	0
order	Sort order (-field for descending, field for ascending)	-

Content options

Parameter	Description	Default
preview	Include draft content (1 = enabled)	0
locale	Locale code for localized content (e.g., en, es)	Default locale
levels	Depth of reference field resolution (1-5)	2

Blog-specific

Parameter	Description
exclude_body	Exclude post body for faster list responses (true/false)
category_slug	Filter posts by category
tag_slug	Filter posts by tag
author_slug	Filter 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