Skip to main content
GET
/
categories
/
List All Categories
curl --request GET \
  --url https://api.buttercms.com/v2/categories/ \
  --header 'Authorization: <api-key>'
{
  "data": [
    {
      "name": "test category",
      "slug": "test-category"
    },
    {
      "name": "Product Updates",
      "slug": "product-updates"
    },
    {
      "name": "Company News",
      "slug": "company-news"
    },
    {
      "name": "Technology",
      "slug": "technology"
    }
  ]
}
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.

Authorizations

​
Authorization
string
header
required

Set the Authorization header to Token your_read_api_token.

Example: Authorization: Token abc123def456

Note: The header value includes the Token prefix.

You can access your API token from your settings page.

Query Parameters

​
auth_token
string

Your ButterCMS read API token

​
include
enum<string>

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.

Available options:
recent_posts
​
locale
string

Filter the embedded recent_posts list to posts in the given locale (e.g. en, es). The category itself is shared across locales and is always returned. When omitted, defaults to your organization's default locale.

Returns 400 if the value is not a locale configured on your organization.

Maximum string length: 10

Response

Categories retrieved successfully

Response structure for listing all categories

​
data
object[]

Array of category objects