> ## 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 Posts

> Retrieve a paginated list of published blog posts sorted by publication date, with filtering and performance options.

Retrieve a paginated list of all published blog posts, automatically sorted
by publication date with the newest posts appearing first. This endpoint is
ideal for building blog listing pages, RSS feeds, or content archives.

**Performance Optimization**: Use the `exclude_body=true` parameter when
building post listing pages to significantly reduce response size by
excluding the full post content. This improves loading performance while
still providing titles, summaries, metadata, and author information needed
for listing displays.


## OpenAPI

````yaml /api/openapi/read_api.yaml get /posts/
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:
  /posts/:
    get:
      tags:
        - Blog posts
      summary: List All Posts
      description: >
        Retrieve a paginated list of all published blog posts, automatically
        sorted

        by publication date with the newest posts appearing first. This endpoint
        is

        ideal for building blog listing pages, RSS feeds, or content archives.


        **Performance Optimization**: Use the `exclude_body=true` parameter when

        building post listing pages to significantly reduce response size by

        excluding the full post content. This improves loading performance while

        still providing titles, summaries, metadata, and author information
        needed

        for listing displays.
      operationId: listAllPosts
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/page_size'
        - name: limit
          in: query
          description: |
            Maximum number of items to return for offset-based pagination.

            **Mutually exclusive with page/page_size parameters.**
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
          example: 5
        - name: offset
          in: query
          description: |
            Number of items to skip before starting to return results.

            **Mutually exclusive with page/page_size parameters.**
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 10
        - $ref: '#/components/parameters/preview'
        - name: locale
          in: query
          description: >
            Return only posts in the given locale (e.g. `en`, `es`). 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
        - name: exclude_body
          in: query
          description: >
            When `true`, excludes the full post body from the response.


            **Performance benefit**: Significantly reduces response size when
            displaying lists of blog posts.
          schema:
            type: boolean
            default: false
          example: true
        - name: author_slug
          in: query
          description: Filter posts by an author's slug.
          schema:
            type: string
          example: api-test
        - name: category_slug
          in: query
          description: Filter posts by a category's slug.
          schema:
            type: string
          example: test-category
        - name: tag_slug
          in: query
          description: Filter posts by a tag's slug.
          schema:
            type: string
          example: test-tag
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: >
            **Success - Blog Posts Retrieved**


            Returns a list of blog posts matching the specified criteria. Posts
            are

            sorted by publish date with the most recent posts first.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PageBasedPostsResponse'
                  - $ref: '#/components/schemas/OffsetBasedPostsResponse'
              examples:
                page_based_pagination:
                  summary: Page-based pagination (default)
                  description: Using ?page=2&page_size=5 parameters
                  value:
                    meta:
                      count: 25
                      next_page: 3
                      previous_page: 1
                    data:
                      - url: http://www.example.com/blog/this-is-a-blog-post
                        created: '2020-10-08T18:29:19.987936Z'
                        updated: '2020-10-09T15:49:54.580309Z'
                        published: '2020-10-08T18:08:00Z'
                        author:
                          first_name: API
                          last_name: Test
                          email: apitest@buttercms.com
                          slug: api-test
                          bio: This is my bio.
                          title: API
                          linkedin_url: https://www.linkedin.com/in/API
                          facebook_url: https://www.facebook.com/API
                          twitter_handle: buttercmsapi
                          profile_image: https://buttercms.com/api.png
                        categories:
                          - name: test category
                            slug: test-category
                        tags:
                          - name: test tag
                            slug: test-tag
                        featured_image: null
                        featured_image_alt: ''
                        slug: this-is-a-blog-post
                        title: This is a blog post
                        body: <p class="">This is a blog post to test the API.</p>
                        summary: This is a blog post to test the API.
                        seo_title: This is a blog post
                        meta_description: This is a blog post to test the API.
                        status: published
                offset_based_pagination:
                  summary: Offset-based pagination
                  description: Using ?limit=5&offset=10 parameters
                  value:
                    meta:
                      count: 25
                      next_offset: 15
                      previous_offset: 5
                    data:
                      - url: http://www.example.com/blog/this-is-a-blog-post
                        created: '2020-10-08T18:29:19.987936Z'
                        updated: '2020-10-09T15:49:54.580309Z'
                        published: '2020-10-08T18:08:00Z'
                        author:
                          first_name: API
                          last_name: Test
                          email: apitest@buttercms.com
                          slug: api-test
                          bio: This is my bio.
                          title: API
                          linkedin_url: https://www.linkedin.com/in/API
                          facebook_url: https://www.facebook.com/API
                          twitter_handle: buttercmsapi
                          profile_image: https://buttercms.com/api.png
                        categories:
                          - name: test category
                            slug: test-category
                        tags:
                          - name: test tag
                            slug: test-tag
                        featured_image: null
                        featured_image_alt: ''
                        slug: this-is-a-blog-post
                        title: This is a blog post
                        body: <p class="">This is a blog post to test the API.</p>
                        summary: This is a blog post to test the API.
                        seo_title: This is a blog post
                        meta_description: This is a blog post to test the API.
                        status: published
                exclude_body_response:
                  summary: Response with exclude_body=true (lighter payload)
                  description: Using page-based pagination with exclude_body parameter
                  value:
                    meta:
                      count: 25
                      next_page: 3
                      previous_page: 1
                    data:
                      - url: http://www.example.com/blog/this-is-a-blog-post
                        created: '2020-10-08T18:29:19.987936Z'
                        updated: '2020-10-09T15:49:54.580309Z'
                        published: '2020-10-08T18:08:00Z'
                        author:
                          first_name: API
                          last_name: Test
                          email: apitest@buttercms.com
                          slug: api-test
                          bio: This is my bio.
                          title: API
                          linkedin_url: https://www.linkedin.com/in/API
                          facebook_url: https://www.facebook.com/API
                          twitter_handle: buttercmsapi
                          profile_image: https://buttercms.com/api.png
                        categories:
                          - name: test category
                            slug: test-category
                        tags:
                          - name: test tag
                            slug: test-tag
                        featured_image: null
                        featured_image_alt: ''
                        slug: this-is-a-blog-post
                        title: This is a blog post
                        summary: This is a blog post to test the API.
                        seo_title: This is a blog post
                        meta_description: This is a blog post to test the API.
                        status: published
        '400':
          description: |
            **Bad Request - Invalid Query Parameters**

            Invalid or malformed query parameters provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Invalid query parameters.
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
        - readTokenAuthHeader: []
        - readTokenAuthQuery: []
components:
  parameters:
    page:
      name: page
      in: query
      description: |
        Page number for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 2
    page_size:
      name: page_size
      in: query
      description: |
        Number of items per page for page-based pagination.

        **Mutually exclusive with limit/offset parameters.**
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
      example: 5
    preview:
      name: preview
      in: query
      description: >
        Set to 1 to return the latest draft version of a page. Useful for
        previewing changes before publishing live. i.e. `&preview=1`. If you are
        trying to view a scheduled page for which the most recent page version
        is published, you must pass the preview parameter to see the scheduled
        changes.


        Set to `1` to access unpublished/draft collection items. Useful for
        staging environments.
      required: false
      schema:
        type: integer
        enum:
          - 0
          - 1
        default: 0
      example: 1
    auth_token:
      name: auth_token
      in: query
      required: false
      schema:
        type: string
      description: |
        Your ButterCMS read API token
      example: your_api_token
  schemas:
    PageBasedPostsResponse:
      type: object
      description: Blog posts response using page-based pagination (default)
      properties:
        meta:
          $ref: '#/components/schemas/PaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostObject'
          description: Array of blog post objects sorted by publish date (newest first)
      required:
        - meta
        - data
    OffsetBasedPostsResponse:
      type: object
      description: Blog posts response using offset-based pagination (alternative)
      properties:
        meta:
          $ref: '#/components/schemas/OffsetPaginationMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlogPostObject'
          description: Array of blog post objects sorted by publish date (newest first)
      required:
        - meta
        - data
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
    PaginationMeta:
      type: object
      properties:
        previous_page:
          type:
            - integer
            - 'null'
          description: Previous page number if it exists
        next_page:
          type:
            - integer
            - 'null'
          description: Next page number if it exists
        count:
          type: integer
          description: Total number of items
    BlogPostObject:
      type: object
      description: Complete blog post object with all fields and related data
      properties:
        url:
          type: string
          format: uri
          description: Full URL to the blog post
          example: http://www.example.com/blog/this-is-a-blog-post
        created:
          type: string
          format: date-time
          description: Timestamp when the blog post was created
          example: '2020-10-08T18:29:19.987936Z'
        updated:
          type: string
          format: date-time
          description: Timestamp when the blog post was last updated
          example: '2020-10-09T15:49:54.580309Z'
        published:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp when the blog post was published
          example: '2020-10-08T18:08:00Z'
        author:
          $ref: '#/components/schemas/BlogPostAuthorObject'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CategoryObject'
          description: Array of categories assigned to the blog post
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagObject'
          description: Array of tags assigned to the blog post
        featured_image:
          type:
            - string
            - 'null'
          format: uri
          description: URL to the featured image, null if no featured image
          example: null
        featured_image_alt:
          type: string
          description: Alt text for the featured image
          example: ''
        slug:
          type: string
          description: URL-friendly slug for the blog post
          example: this-is-a-blog-post
        title:
          type: string
          description: Title of the blog post
          example: This is a blog post
        body:
          type: string
          description: HTML content body of the blog post (excluded if exclude_body=true)
          example: <p class="">This is a blog post to test the API.</p>
        summary:
          type: string
          description: Plain text summary of the blog post
          example: This is a blog post to test the API.
        seo_title:
          type: string
          description: SEO-optimized title for the blog post
          example: This is a blog post
        meta_description:
          type: string
          description: Meta description for SEO and social sharing
          example: This is a blog post to test the API.
        status:
          type: string
          enum:
            - draft
            - published
            - scheduled
          description: Publication status of the blog post
          example: published
        scheduled:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Timestamp when the blog post is scheduled to be published. If not
            scheduled, this field will be null
          example: null
    OffsetPaginationMeta:
      type: object
      description: Pagination metadata for limit/offset pagination
      properties:
        count:
          type: integer
          description: Total number of items
          example: 25
        next_offset:
          type:
            - integer
            - 'null'
          description: Offset for the next page, null if no next page
          example: 20
        previous_offset:
          type:
            - integer
            - 'null'
          description: Offset for the previous page, null if no previous page
          example: null
    BlogPostAuthorObject:
      type: object
      description: Author information for blog posts
      properties:
        first_name:
          type: string
          description: Author's first name
          example: API
        last_name:
          type: string
          description: Author's last name
          example: Test
        email:
          type: string
          format: email
          description: Author's email address
          example: apitest@buttercms.com
        slug:
          type: string
          description: Author's URL-friendly slug
          example: api-test
        bio:
          type: string
          description: Author's biography
          example: This is my bio.
        title:
          type: string
          description: Author's professional title
          example: API
        linkedin_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's LinkedIn profile URL
          example: https://www.linkedin.com/in/API
        facebook_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Facebook profile URL
          example: https://www.facebook.com/API
        twitter_handle:
          type: string
          description: Author's Twitter handle
          example: buttercmsapi
        instagram_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Instagram profile URL
          example: https://www.instagram.com/API
        pinterest_url:
          type:
            - string
            - 'null'
          format: uri
          description: Author's Pinterest profile URL
          example: https://www.pinterest.com/API
        profile_image:
          type:
            - string
            - 'null'
          format: uri
          description: URL to author's profile image
          example: https://buttercms.com/api.png
    CategoryObject:
      type: object
      description: Category information for blog posts
      properties:
        name:
          type: string
          description: Display name of the category
          example: test category
        slug:
          type: string
          description: URL-friendly slug of the category
          example: test-category
    TagObject:
      type: object
      description: Tag information for blog posts
      properties:
        name:
          type: string
          description: Display name of the tag
          example: test tag
        slug:
          type: string
          description: URL-friendly slug of the tag
          example: test-tag
  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.

````