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

# Delete Blog Post via Write API

> Soft-delete an existing blog post via the Write API. The post is marked as deleted but its data is preserved.

Delete an existing blog post using a soft delete operation that marks the post as deleted while preserving the content for potential recovery. This approach ensures data safety while removing posts from public visibility.

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

**Soft Delete Behavior**: The post is marked as deleted in the system and will no longer appear in blog listings, search results, RSS feeds, or other public endpoints. However, the actual content and metadata are preserved in the database, allowing for potential recovery through support channels if needed.

**Localization**: Use the `locale` query parameter to specify which locale variant to delete (e.g. `?locale=es`). When omitted, the post's current locale is used. If the specified locale variant does not exist, a 404 Not Found response is returned.

**Access Control**: You can only delete blog posts that belong to your organization. Attempting to delete posts from other organizations will result in a 404 Not Found response, ensuring proper data isolation and security.


## OpenAPI

````yaml /api/openapi/write_api.yaml delete /posts/{slug}/
openapi: 3.1.0
info:
  title: ButterCMS Write API
  version: 2.0.0
  description: >
    Write endpoints for the ButterCMS API — create, update, and delete Pages,
    Collections, and Blog Posts.
  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:
  - writeTokenAuth: []
tags:
  - name: Pages
    description: >
      Create new pages using ButterCMS Write API. Programmatically create
      content to enable powerful use cases and scale your content faster.


      Note: For Pages, PUT behaves like PATCH (partial update). Use either
      method to perform partial updates.
  - name: Collections
    description: >
      Create, update, and delete Collection items using ButterCMS Write API.
      Collections are user-defined content structures with completely
      customizable field schemas.
  - name: Blog posts
    description: >
      Create, update, and delete blog posts using ButterCMS Write API. Blog
      posts support rich content including HTML body, categories, tags, featured
      images, and SEO metadata.
paths:
  /posts/{slug}/:
    delete:
      tags:
        - Blog posts
      summary: Delete Blog Post via Write API
      description: >
        Delete an existing blog post using a soft delete operation that marks
        the post as deleted while preserving the content for potential recovery.
        This approach ensures data safety while removing posts from public
        visibility.


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


        **Soft Delete Behavior**: The post is marked as deleted in the system
        and will no longer appear in blog listings, search results, RSS feeds,
        or other public endpoints. However, the actual content and metadata are
        preserved in the database, allowing for potential recovery through
        support channels if needed.


        **Localization**: Use the `locale` query parameter to specify which
        locale variant to delete (e.g. `?locale=es`). When omitted, the post's
        current locale is used. If the specified locale variant does not exist,
        a 404 Not Found response is returned.


        **Access Control**: You can only delete blog posts that belong to your
        organization. Attempting to delete posts from other organizations will
        result in a 404 Not Found response, ensuring proper data isolation and
        security.
      operationId: deleteBlogPost
      parameters:
        - name: slug
          in: path
          required: true
          description: >
            The slug of the blog post to delete.


            **Important**: The URL must end with a trailing slash
            (`/v2/posts/your-slug/`).
          schema:
            type: string
            maxLength: 100
          example: this-is-a-blog-post
        - name: locale
          in: query
          description: >
            Delete this locale variant of the post (e.g. `en`, `es`). When
            omitted, deletes the post in its current locale. Returns 404 if the
            locale variant does not exist.
          required: false
          schema:
            type: string
            maxLength: 10
          example: en
      responses:
        '204':
          description: >
            **No Content - Blog Post Successfully Deleted**


            The blog post has been successfully deleted (soft delete). The
            response body is empty.


            **Note**: This is a soft delete operation. The post is marked as
            deleted but not physically removed from the system.
        '401':
          $ref: '#/components/responses/UnauthorizedWriteResponse'
        '403':
          description: >
            **Forbidden - Insufficient Permissions**


            Your API token does not have write permissions. Only write-enabled
            API tokens can delete blog posts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Your API token does not allow writes.
        '404':
          description: >
            **Not Found - Blog Post Does Not Exist or Already Deleted**


            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

            - The blog post has already been deleted

            - You don't have access to the blog post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Not found.
      security:
        - writeTokenAuth: []
components:
  responses:
    UnauthorizedWriteResponse:
      description: >
        **Unauthorized - Invalid or Missing Write API Token**


        No valid write API key provided. The API token you use for reading from
        the ButterCMS API

        will not allow you to create content. You need a different write-enabled
        token.

        Contact support@buttercms.com to get yours.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            detail: Authentication credentials were not provided
  schemas:
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
  securitySchemes:
    writeTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Write-enabled API token required for creating content.


        The API token you use for reading from the ButterCMS API will not allow
        you to create content in the API. For this you will need to use a
        different write-enabled token. Chat or email support@buttercms.com to
        get yours.


        Set the `Authorization` header to `Token your_write_api_token`.


        Example: `Authorization: Token abc123def456`


        Your write-enabled token should never be used anywhere it would be
        exposed, e.g. in client-side JavaScript.

````