Skip to main content
PATCH
/
posts
/
{slug}
curl --request PATCH \
  --url https://api.buttercms.com/v2/posts/{slug}/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "slug": "the-new-post-slug",
  "body": "<h1>Updated</h1><p>This blog post was updated via API</p>"
}
'
{
  "status": "pending"
}
Update an existing blog post using partial updates, allowing you to modify specific fields while preserving all other content. This endpoint is perfect for content updates, SEO optimization, or adding new media to existing posts. Partial Update Flexibility: All fields in the request body are optional - include only the fields you want to modify. Any omitted fields will retain their current values, making it safe to update specific content without affecting the entire post structure.
Important: The URL must append a trailing slash to the blog post slug in the URL path (/v2/posts/your-post-slug/). This is required for the endpoint to function correctly.
Scheduling Limitations: Blog post scheduling is not available through the Write API. Any scheduled parameters in your request will be silently ignored (not treated as errors), allowing you to safely update posts that are currently scheduled without affecting their publication timing. Media Integration: Include upload_images_to_media_library=true in your request to automatically download and upload any image URLs within the post body to your ButterCMS media library. This ensures reliable hosting and CDN performance for your content images. Asynchronous Processing: This endpoint returns 202 Accepted immediately to ensure fast response times for your application. The actual update processing, including media uploads, content validation, and webhook notifications, happens in the background processing queue.

Authorizations

​
Authorization
string
header
required

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.

Path Parameters

​
slug
string
required

The slug of the blog post to update.

Important: The URL must end with a trailing slash (/v2/posts/your-slug/).

Maximum string length: 100

Body

application/json

Request schema for updating an existing blog post. All fields are optional for partial updates.

Note: If scheduled timestamp or status: "scheduled" are provided, they will be ignored and warning messages will be included in the response.

​
title
string

The title of the blog post

Maximum string length: 200
Example:

"Updated Blog Post Title"

​
slug
string

The slug of the blog post.

Auto-Slugification: The API automatically converts your input to a valid slug format using unicode slugification.

Maximum string length: 100
Example:

"updated-blog-post-slug"

​
status
enum<string>

The status of the post.

Note: "scheduled" status will be ignored and a warning message will be included in the response.

Available options:
draft,
published,
scheduled
Example:

"published"

​
author
any
​
categories
string[]

Array of category names. Categories will be created if they don't exist.

Example:
["Updated Category", "New Category"]
​
tags
string[]

Array of tag names. Tags will be created if they don't exist.

Example:
["updated", "refresh", "api"]
​
featured_image
string<uri>

Can be a remote URL to an image.

The image will always be uploaded to the media library (the value of upload_images_to_media_library is ignored for featured images).

Example:

"https://example.com/updated-featured-image.jpg"

​
featured_image_alt
string

Alt text for the featured image

Maximum string length: 250
Example:

"Updated featured image alt text."

​
body
string

Should be a string of escaped HTML.

In case it contains any remote URLs to images, the upload_images_to_media_library flag controls the behavior.

Example:

"<h1>Updated Content</h1><p>This blog post was updated via API</p>"

​
summary
string

Plain-text summary of the blog post

Maximum string length: 2000
Example:

"Updated summary of the blog post."

​
seo_title
string

SEO title for HTML title tag

Maximum string length: 100
Example:

"Updated SEO Title"

​
meta_description
string

Meta description for SEO and social sharing

Example:

"Updated meta description for better SEO."

​
upload_images_to_media_library
boolean
default:false

Defaults to false.

If set to true, any image URLs in the body property will be uploaded to the Butter Media Library and the original URL will be replaced with the media library URL.

Note: Featured images are always uploaded regardless of this setting.

Example:

true

​
scheduled
string<date-time>

Note: This field will be ignored - scheduled timestamps cannot be created or altered via write API.

If provided, this field will be removed from the request and a warning message will be included in the response.

Example:

"2024-12-25T10:00:00Z"

Response

Accepted - Post Update Initiated

The update request has been accepted and will be processed asynchronously. The response may include warning messages if certain fields were ignored (such as scheduling-related fields).

Warning Messages: If you provided scheduled timestamp or status: "scheduled", these will be ignored and warning messages will be included in the response.

Success response for blog post updates (202 Accepted). May include warning messages for ignored fields.

​
status
enum<string>

Indicates that the blog post update is being processed asynchronously

Available options:
pending
Example:

"pending"

​
warning: scheduled field
string

Warning message when scheduled field is ignored

Example:

"Scheduled timestamps cannot be created or altered via write API. This field will be ignored."

​
warning: status field
string

Warning message when scheduled status is ignored

Example:

"A blog post's status cannot be set asscheduledvia write API at this time. This field will be ignored."

​
{key}
string

Additional warning messages for other ignored fields