> ## Documentation Index > Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List All Categories > Retrieve a complete list of blog post categories with optional recent post data for category-based navigation. 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. ## OpenAPI ````yaml /api/openapi/read_api.yaml get /categories/ openapi: 3.1.0 info: title: ButterCMS Read API version: 2.0.0 description: > Read endpoints for the ButterCMS API — Pages, Collections, Blog Posts, Blog Metadata, and Feeds. contact: email: support@buttercms.com license: name: ButterCMS Terms of Service url: https://buttercms.com/terms/ servers: - url: https://api.buttercms.com/v2 description: ButterCMS API v2 security: - readTokenAuthHeader: [] - readTokenAuthQuery: [] tags: - name: Pages description: > 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. - name: Collections description: > 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. - name: Blog posts description: > Retrieve blog posts from your ButterCMS account. List blog posts with pagination and filtering options, or retrieve individual posts by slug. - name: Blog metadata description: > Retrieve blog-related metadata including authors, categories, and tags. These endpoints provide access to the organizational structure of your blog content. - name: Feeds and utilities description: > 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. - name: Images - Info description: > ButterCMS has an integration with [Filestack](https://www.filestack.com/docs/api/processing/) 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](https://www.filestack.com/docs/api/processing/). paths: /categories/: get: tags: - Blog metadata summary: List All Categories description: > 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. operationId: listAllCategories parameters: - $ref: '#/components/parameters/auth_token' - name: include in: query required: false schema: type: string enum: - recent_posts description: > 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. example: recent_posts - name: locale in: query description: > 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. required: false schema: type: string maxLength: 10 example: en responses: '200': description: Categories retrieved successfully content: application/json: schema: $ref: '#/components/schemas/ListCategoriesResponse' examples: basic_categories: summary: Basic categories list value: data: - name: test category slug: test-category - name: Product Updates slug: product-updates - name: Company News slug: company-news - name: Technology slug: technology categories_with_posts: summary: Categories with recent posts included value: data: - name: Product Updates slug: product-updates recent_posts: - slug: new-features-release title: Exciting New Features in Our Latest Release published: '2024-01-20T10:00:00.000Z' - slug: api-improvements title: API Performance Improvements published: '2024-01-15T14:30:00.000Z' - name: Technology slug: technology recent_posts: - slug: future-of-web-development title: The Future of Web Development published: '2024-01-18T11:00:00.000Z' '401': $ref: '#/components/responses/UnauthorizedResponse' security: - readTokenAuthHeader: [] - readTokenAuthQuery: [] components: parameters: auth_token: name: auth_token in: query required: false schema: type: string description: | Your ButterCMS read API token example: your_api_token schemas: ListCategoriesResponse: type: object description: Response structure for listing all categories properties: data: type: array items: $ref: '#/components/schemas/CategoryObjectWithPosts' description: Array of category objects CategoryObjectWithPosts: type: object description: Category information with optional recent posts properties: name: type: string description: Display name of the category example: Product Updates slug: type: string description: URL-friendly slug of the category example: product-updates recent_posts: type: array items: $ref: '#/components/schemas/CategoryRecentPost' description: >- Array of recent posts in this category (only included when include=recent_posts parameter is used) ErrorResponse: type: object properties: detail: type: string description: Error message describing what went wrong example: Authentication credentials were not provided CategoryRecentPost: type: object description: Simplified blog post information for category's recent posts properties: slug: type: string description: Blog post slug/identifier example: new-features-release title: type: string description: Blog post title example: Exciting New Features in Our Latest Release published: type: string format: date-time description: Publication date and time in ISO 8601 format example: '2024-01-20T10:00:00.000Z' responses: UnauthorizedResponse: description: Unauthorized - Invalid or missing API token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Missing API token value: detail: Authentication credentials were not provided invalid_token: summary: Invalid API token value: detail: Invalid token securitySchemes: readTokenAuthHeader: type: apiKey in: header name: Authorization description: | 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. readTokenAuthQuery: type: apiKey in: query name: auth_token description: > Pass your API token via the `auth_token` parameter on every request: `?auth_token=your_read_api_token`. You can access your API token from your settings page. Requests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS. ````