Update Blog Post via Write API
Partially update an existing blog post via the Write API with support for flexible field modification and status changes.
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
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.
Query Parameters
Body
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.
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.
true
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.
Was this page helpful?