> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Collection Item (Full)

> Fully replace an existing Collection item via PUT request, overwriting all fields with the provided data.

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.


## OpenAPI

````yaml /api/openapi/write_api.yaml put /content/{collection_key}/{item_id}/
openapi: 3.1.0
info:
  title: ButterCMS Write API
  version: 2.0.0
  description: >
    Write endpoints for the ButterCMS API — create, update, and delete Pages,
    Collections, and Blog Posts.
  contact:
    email: support@buttercms.com
  license:
    name: ButterCMS Terms of Service
    url: https://buttercms.com/terms/
servers:
  - url: https://api.buttercms.com/v2
    description: ButterCMS API v2
security:
  - writeTokenAuth: []
tags:
  - name: Pages
    description: >
      Create new pages using ButterCMS Write API. Programmatically create
      content to enable powerful use cases and scale your content faster.


      Note: For Pages, PUT behaves like PATCH (partial update). Use either
      method to perform partial updates.
  - name: Collections
    description: >
      Create, update, and delete Collection items using ButterCMS Write API.
      Collections are user-defined content structures with completely
      customizable field schemas.
  - name: Blog posts
    description: >
      Create, update, and delete blog posts using ButterCMS Write API. Blog
      posts support rich content including HTML body, categories, tags, featured
      images, and SEO metadata.
paths:
  /content/{collection_key}/{item_id}/:
    put:
      tags:
        - Collections
      summary: Update Collection Item (Full)
      description: >
        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.
      operationId: updateCollectionItem
      parameters:
        - name: collection_key
          in: path
          required: true
          schema:
            type: string
            maxLength: 100
          description: >
            The unique identifier/slug of the Collection containing the item to
            update.


            Must match an existing collection in your organization.
          example: team_members
        - name: item_id
          in: path
          required: true
          schema:
            type: string
            maxLength: 50
          description: >
            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.
          example: '123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionItemRequest'
            examples:
              without_locales_full_update:
                summary: Full update without locales
                description: Complete replacement of collection item fields
                value:
                  status: published
                  fields:
                    field1_key: Updated field value
                    field2_key: Another updated value
                    contact_email: updated@example.com
              with_locales_full_update:
                summary: Full update with locales
                description: Complete replacement with multi-locale support
                value:
                  status: published
                  fields:
                    en:
                      field1_key: Updated English value
                      field2_key: Another English value
                    es:
                      field1_key: Valor actualizado en español
                      field2_key: Otro valor en español
              reference_fields_update:
                summary: Reference field updates
                description: Updating relationships to pages and other collections
                value:
                  status: published
                  fields:
                    related_page: updated-page-slug
                    tags:
                      - 4
                      - 5
                      - 6
                    category: null
      responses:
        '202':
          $ref: '#/components/responses/CollectionItemAcceptedResponse'
        '400':
          description: Bad Request - Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                validation_errors:
                  summary: Field validation errors
                  value:
                    field1_key:
                      - This field is required.
                    status:
                      - Valid status values are 'draft' and 'published'
                invalid_references:
                  summary: Reference field errors
                  value:
                    related_page:
                      - Page with slug 'nonexistent-page' not found.
                    tags:
                      - Collection item with ID 999 not found.
        '401':
          description: Unauthorized - Invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing API token
                  value:
                    detail: Authentication credentials were not provided
                invalid_token:
                  summary: Invalid API token
                  value:
                    detail: Invalid token
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                write_permission:
                  summary: Token lacks write permissions
                  value:
                    detail: Token does not have write permissions
        '404':
          description: Not Found - Collection or item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                collection_not_found:
                  summary: Collection not found
                  value:
                    detail: Collection not found
                item_not_found:
                  summary: Collection item not found
                  value:
                    detail: Collection item not found
      security:
        - writeTokenAuth: []
components:
  schemas:
    UpdateCollectionItemRequest:
      type: object
      description: >
        **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)
      properties:
        status:
          $ref: 60cafcd7-6cdb-4012-a76a-1916542e84d4
          description: |
            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:
          type: object
          description: >
            **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
          additionalProperties: true
          example:
            name: Updated Team Member Name
            position: Lead Developer
            bio: Updated biography content
    ValidationErrorResponse:
      type: object
      description: >-
        Response for validation errors (400 Bad Request) - supports both
        field-specific errors and general error messages
      oneOf:
        - type: object
          description: >-
            Field-specific validation errors (used by Pages, Blog Posts, and
            Collections)
          additionalProperties:
            type: array
            items:
              type: string
          example:
            title:
              - You must specify a page title.
            slug:
              - You must specify a page slug.
        - type: object
          description: General error message (used for organization limits, etc.)
          properties:
            error:
              type: string
              description: Error message
          example:
            error: >-
              Cannot create a new Collection Item. Collection Item Limit
              Reached.
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message describing what went wrong
          example: Authentication credentials were not provided
  responses:
    CollectionItemAcceptedResponse:
      description: Collection item operation accepted for async processing
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - pending
                description: >-
                  Indicates the request was accepted and is being processed
                  asynchronously
                example: pending
          example:
            status: pending
  securitySchemes:
    writeTokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >
        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.

````