Skip to main content
PATCH
/
content
/
{collection_key}
/
{item_id}
curl --request PATCH \
  --url https://api.buttercms.com/v2/content/{collection_key}/{item_id}/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "published",
  "fields": {
    "field2_key": "Only this field gets updated"
  }
}
'
{
  "status": "pending"
}
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, status, 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.
Important: The URL must include a trailing slash after the item ID (e.g., /v2/content/my-collection/123/). This is required for the endpoint to function correctly.
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. 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

​
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: 100
​
item_id
string
required

The unique identifier of the collection item to update.

Important: The URL must end with a trailing slash after this parameter.

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 optional for partial updates (e.g., status-only updates)
​
status
any

Publication status of the collection item.

  • If omitted in PATCH requests, the current status is preserved
  • If provided in PUT/PATCH requests, the status will be updated
​
fields
object

Optional for PATCH, Required for PUT. 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

Example:
{
  "name": "Updated Team Member Name",
  "position": "Lead Developer",
  "bio": "Updated biography content"
}

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"