Skip to main content
PATCH
Perform a partial update (PATCH) of an existing Collection item, updating only the fields you specify while preserving all other content. This method is ideal for targeted updates without affecting the entire item structure. Update Method: PATCH updates only the fields included in your request body, leaving all other fields unchanged. This differs from PUT operations, which replace the entire item. Use PATCH when you want to modify specific fields while preserving existing content, relationships, and metadata. Partial Update Intelligence: Reference fields, timestamps, and any omitted content fields automatically retain their current values. This allows you to safely update specific content without worrying about accidentally clearing other important data. Status: Send status: published to make the changes live. If status is omitted, the changes are saved as a draft revision and the live content does not change. The Write API cannot publish an item that was created as a draft; publish it from the ButterCMS dashboard. The fields key is required, so a status-only PATCH returns 400. Item Identification: The unique item ID can be found in the meta field of any collection item when retrieved through GET requests. This identifier remains constant throughout the item’s life cycle. Reference Field Handling: When updating reference fields, use page slugs for Page references and item IDs for Collection references. If you omit reference fields from your request, existing references remain completely unchanged, making it safe to update other content without affecting relationships. Asynchronous Processing: This endpoint returns 202 Accepted immediately to ensure fast response times. The actual update processing, including media uploads, reference validation, and webhook triggers, 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

​
collection_key
string
required

The unique identifier/slug of the Collection containing the item to update.

Must match an existing collection in your organization.

Maximum string length: 50
​
item_id
string
required

The unique identifier of the collection item to update.

This ID can be found in the meta field of collection items returned by GET operations.

Maximum string length: 50

Body

application/json

Flexible request schema for updating collection items - supports both single-locale and multi-locale formats.

Update Types:

  • PUT: Requires fields for full replacement
  • PATCH: fields is required too; include only the fields you want to change. A status-only PATCH without fields returns 400.
​
fields
object
required

Required for PUT and PATCH. Collection item field data with flexible format support.

System automatically detects the format based on the structure of the object:

Without Locales Format: Direct field properties (e.g., name, position, bio) With Locales Format: Locale codes as keys (e.g., en, es, fr)

Update Behavior:

  • PUT: All fields should be provided (full replacement)
  • PATCH: Only provided fields are updated, others remain unchanged

Dynamic Schema: Field names and types are completely user-defined based on your collection configuration.

Reference Fields: Support updating relationships to Pages and other Collections

  • Page references: Use page slugs (e.g., "related_page": "example-slug")
  • Collection references: Use collection item IDs (e.g., "tags": [1, 2, 3])
  • Remove references: Use "", [], or null

Media Fields: Support remote URL upload - content is automatically uploaded to ButterCMS. Provide an object {"url": "https://...", "alt": "Descriptive alt text"} to also set alt text; a plain URL string replaces any existing alt text.

Example:
​
status
any

Whether the submitted field values are saved as a draft or published. Defaults to draft when omitted.

  • published: the new values are served by the Read API without preview=1
  • draft or omitted: the new values are saved as a draft revision and the live content does not change

This does not change the item's own publication state. A collection item created as a draft stays hidden from production reads after a PUT or PATCH with status: published; publish it from the ButterCMS dashboard.

Response

Collection item operation accepted for async processing

​
status
enum<string>

Indicates the request was accepted and is being processed asynchronously

Available options:
pending
Example:

"pending"