Skip to main content
PUT
/
content
/
{collection_key}
/
{item_id}
curl --request PUT \
  --url https://api.buttercms.com/v2/content/{collection_key}/{item_id}/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "published",
  "fields": {
    "field1_key": "Updated field value",
    "field2_key": "Another updated value",
    "contact_email": "updated@example.com"
  }
}
'
{
  "status": "pending"
}
Perform a full update (PUT) of an existing Collection item, completely replacing the item with the provided data. This operation is ideal when you need to ensure all fields are synchronized with your source data or when making comprehensive changes. Update Method: PUT replaces the entire item with your request data, similar to recreating the item from scratch. This differs from PATCH operations, which only update specific fields. Use PUT when you want to ensure complete data consistency or when your workflow involves regenerating entire items.
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 and is required for all update and delete operations. Reference Field Updates: When updating reference fields, use page slugs for Page references and item IDs for Collection references. To remove existing references, provide empty strings (""), empty arrays ([]), or null values depending on the field type and whether it’s a single or multi-reference field. Asynchronous Processing: This endpoint returns 202 Accepted immediately to ensure fast response times. The actual update processing, including media uploads, reference resolution, 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"