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

# Retrieve Single Post

> Retrieve a specific blog post by slug with complete content, metadata, and next/previous post navigation.

Retrieve a specific blog post by its unique slug, including complete post content, metadata, and navigation information. This endpoint is ideal for building individual blog post pages with full content display.

**Universal Access**: This endpoint retrieves posts regardless of their publication status (published, draft, or scheduled), making it perfect for preview functionality and content management workflows. Note that draft and scheduled posts won't appear in listing endpoints unless preview mode is specifically enabled.

**Navigation Support**: The response includes a helpful `meta` object containing `next_post` and `previous_post` navigation links, allowing you to easily implement "Previous/Next" navigation on your blog post pages without additional API calls.

> **Important**: You must append a trailing slash to the URL path: `/v2/posts/your-post-slug/`. This is required for the endpoint to function correctly.


## OpenAPI

````yaml /api/openapi/read_api.yaml get /posts/{slug}/
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/{slug}/:
    get:
      tags:
        - Blog posts
      summary: Retrieve Single Post
      description: >
        Retrieve a specific blog post by its unique slug, including complete
        post content, metadata, and navigation information. This endpoint is
        ideal for building individual blog post pages with full content display.


        **Universal Access**: This endpoint retrieves posts regardless of their
        publication status (published, draft, or scheduled), making it perfect
        for preview functionality and content management workflows. Note that
        draft and scheduled posts won't appear in listing endpoints unless
        preview mode is specifically enabled.


        **Navigation Support**: The response includes a helpful `meta` object
        containing `next_post` and `previous_post` navigation links, allowing
        you to easily implement "Previous/Next" navigation on your blog post
        pages without additional API calls.


        > **Important**: You must append a trailing slash to the URL path:
        `/v2/posts/your-post-slug/`. This is required for the endpoint to
        function correctly.
      operationId: retrieveSinglePost
      parameters:
        - name: slug
          in: path
          required: true
          description: >
            The unique slug of the blog post to retrieve.


            **Important**: The URL must end with a trailing slash
            (`/v2/posts/your-slug/`).
          schema:
            type: string
            maxLength: 100
          example: hello-world
        - name: locale
          in: query
          description: >
            Return the locale variant of this post (e.g. `en`, `es`). Slugs are
            unique within a blog, so the slug identifies a specific post; this
            parameter follows the post's locale group to return its sibling
            translation. Sibling translations may have different slugs from the
            post identified in the URL path. When omitted, defaults to the
            locale the post itself was created in.


            Returns `404` if no sibling exists in the requested locale (or the
            post has no locale group). Returns `400` if the value is not a
            locale configured on your organization.
          required: false
          schema:
            type: string
            maxLength: 10
          example: en
        - $ref: '#/components/parameters/auth_token'
      responses:
        '200':
          description: >
            **Success - Blog Post Retrieved**


            Returns the complete blog post object along with navigation metadata
            for browsing between posts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveSinglePostResponse'
              examples:
                published_post:
                  summary: Published blog post with navigation
                  value:
                    meta:
                      next_post: null
                      previous_post:
                        slug: >-
                          google-analytics-is-now-integrated-with-your-butter-blog
                        title: >-
                          Google Analytics is now integrated with your Butter
                          blog
                        featured_image: >-
                          https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/
                    data:
                      url: http://www.example.com/blog/hello-world
                      created: '2015-06-12T13:59:32.441289Z'
                      published: '2015-06-12T00:00: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: hello-world
                      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
                draft_post_preview:
                  summary: >-
                    Draft post accessible via direct slug (preview
                    functionality)
                  value:
                    meta:
                      next_post:
                        slug: upcoming-blog-post
                        title: Upcoming Blog Post
                        featured_image: null
                      previous_post: null
                    data:
                      url: http://www.example.com/blog/draft-post-preview
                      created: '2023-12-01T14:30:00.000000Z'
                      published: null
                      author:
                        first_name: Content
                        last_name: Creator
                        email: creator@example.com
                        slug: content-creator
                        bio: Creating amazing content.
                        title: Content Creator
                        linkedin_url: null
                        facebook_url: null
                        twitter_handle: '@creator'
                        profile_image: null
                      categories: []
                      tags: []
                      featured_image: https://example.com/draft-image.jpg
                      featured_image_alt: Draft post image
                      slug: draft-post-preview
                      title: Draft Post Preview
                      body: >-
                        <h1>Preview Content</h1><p>This is a draft post that can
                        be previewed via direct slug access.</p>
                      summary: A draft post demonstrating preview functionality.
                      seo_title: Draft Post Preview
                      meta_description: Preview of draft content via direct slug access.
                      status: draft
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          description: >
            **Not Found - Blog Post Does Not Exist**


            The blog post with the specified slug was not found. This can happen
            if:


            - The blog post doesn't exist

            - The blog post belongs to a different organization

            - You don't have access to the blog post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Not found.
      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:
    RetrieveSinglePostResponse:
      type: object
      description: Response for retrieving a single blog post with navigation metadata
      properties:
        meta:
          $ref: '#/components/schemas/SinglePostMeta'
        data:
          $ref: '#/components/schemas/BlogPostObject'
          description: Complete blog post object with all fields and related data
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
    SinglePostMeta:
      type: object
      description: Navigation metadata for single blog post responses
      properties:
        next_post:
          anyOf:
            - $ref: '#/components/schemas/PostNavigationObject'
            - type: 'null'
          description: Next blog post for navigation, null if no next post exists
        previous_post:
          anyOf:
            - $ref: '#/components/schemas/PostNavigationObject'
            - type: 'null'
          description: Previous blog post for navigation, null if no previous post exists
    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
    PostNavigationObject:
      type: object
      description: Navigation object containing essential information for blog post links
      properties:
        slug:
          type: string
          description: URL-friendly slug of the post for navigation
          example: google-analytics-is-now-integrated-with-your-butter-blog
        title:
          type: string
          description: Title of the post for display in navigation
          example: Google Analytics is now integrated with your Butter blog
        featured_image:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            URL to the featured image for navigation thumbnails, null if no
            featured image
          example: https://d2devwt40at1e2.cloudfront.net/api/file/etSDYJUIFDADGEEAQ/
    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.

````