Skip to main content
PATCH
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. PUT Support: PUT requests to the same URL are accepted and behave exactly like PATCH (partial update). 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. Localization: Use the locale query parameter to target a specific locale variant (e.g. ?locale=es). When omitted, updates the post in its current locale. If the locale variant does not yet exist, a new locale variant is created and linked to the original post — this is the primary way to create translations of existing blog posts. 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. Write API access is a paid add-on for Advanced and Professional plans, enabled from the Billing page of your account. It isn't offered on Basic plans.

Set the Authorization header to Token your_write_api_token. The ?auth_token= query parameter also works for write requests, but a header is safer because URLs are more likely to be logged.

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.

Maximum string length: 100

Query Parameters

​
locale
string

Target a specific locale variant (e.g. en, es). When omitted, updates the post in its current locale. If the locale variant does not exist, a new one is created and linked to the original post.

Maximum string length: 10

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:
​
tags
string[]

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

Example:
​
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

Created - New Locale Variant

Returned instead of 202 when ?locale= names a configured locale that doesn't yet exist for this post. A new locale variant is created, copying content from the source variant (tags and categories are copied too, unless explicitly provided in the request body).

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