Retrieve Category

Retrieve a specific blog post category by slug with optional recent posts integration.

GET /categories/{slug}

Retrieve Category

cURL

curl --request GET \
  --url https://api.buttercms.com/v2/categories/{slug}/ \
  --header 'Authorization: <api-key>'

200

basic_category

{ "data": { "name": "Product Updates", "slug": "product-updates" } }

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.

Authorizations

readTokenAuthHeaderreadTokenAuthQuery

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.

Path Parameters

slug · string · required

The unique slug identifier of the category to retrieve.

Query Parameters

auth_token · string

Your ButterCMS read API token

include · enum<string>

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).

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

200

application/json

Category retrieved successfully

Response structure for retrieving a single category

data · object

Single category object

Show child attributes