---
updatedAt: 2026-05-18T15:08:55.000Z
agentTools:
  siteIndex: https://documentation.bloomreach.com/llms.txt
  projectIndex: https://documentation.bloomreach.com/data-hub/llms.txt
---

# Update collection

Updates an existing item collection. Requires a complete collection object. The name field and other immutable fields will not be modified even if provided.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Bloomreach Item Collections API",
    "description": "API for Bloomreach Item Collections",
    "version": "1.0.0",
    "license": {
      "name": "unlisted",
      "identifier": "unlisted"
    },
    "contact": {
      "email": "support@bloomreach.com",
      "name": "Bloomreach",
      "url": "https://www.bloomreach.com/docs/item-collections"
    }
  },
  "servers": [
    {
      "url": "https://api.bloomreach.com",
      "description": "Server description"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "Collections",
      "description": "Operations with item collections"
    }
  ],
  "paths": {
    "/api/cde/v1/workspaces/{workspace_id}/item-collections/{collection_name}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/workspace_id"
        },
        {
          "$ref": "#/components/parameters/collection_name"
        }
      ],
      "put": {
        "tags": [
          "Collections"
        ],
        "summary": "Update collection",
        "description": "Updates an existing item collection. Requires a complete collection object. The name field and other immutable fields will not be modified even if provided.",
        "operationId": "update_collection",
        "requestBody": {
          "description": "Complete collection object. All modifiable fields must be provided. Immutable fields like 'name' will be ignored.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "description": {
                    "$ref": "#/components/schemas/CollectionDescription"
                  },
                  "display_name": {
                    "$ref": "#/components/schemas/CollectionDisplayName"
                  },
                  "item_types": {
                    "$ref": "#/components/schemas/CollectionItemTypes"
                  }
                },
                "maxProperties": 100
              },
              "examples": {
                "full_object": {
                  "summary": "Complete collection object",
                  "description": "Update with a complete collection object including all modifiable fields.",
                  "value": {
                    "name": "en_us",
                    "display_name": "Updated site.com/en/us items",
                    "description": "Updated product data for site.com/en/us",
                    "item_types": [
                      {
                        "type": "product",
                        "relationships": [
                          "variant"
                        ]
                      }
                    ]
                  }
                },
                "item_types": {
                  "summary": "Update item types",
                  "description": "Update the collection's supported item types and their relationships.",
                  "value": {
                    "item_types": [
                      {
                        "type": "product",
                        "relationships": [
                          "variant"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update Collection",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "title": "Response Update Collection",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ItemCollection"
                    },
                    "success": {
                      "$ref": "#/components/schemas/ResponseSuccessIndicator"
                    },
                    "details": {
                      "$ref": "#/components/schemas/Details"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ResponseMeta"
                    }
                  },
                  "required": [
                    "data",
                    "success",
                    "details",
                    "meta"
                  ]
                },
                "examples": {
                  "full_object": {
                    "$ref": "#/components/examples/UpdateCollectionFullObject"
                  },
                  "item_types": {
                    "$ref": "#/components/examples/UpdateCollectionItemTypes"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "401": {
            "$ref": "#/components/responses/ErrorResponse"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitedResponse"
          },
          "500": {
            "$ref": "#/components/responses/ErrorResponse"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Basic Authentication using API credentials. The credentials should be Base64-encoded in the format 'username:password' where username is the API group key name and password is the API group key secret."
      }
    },
    "parameters": {
      "workspace_id": {
        "name": "workspace_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid",
          "minLength": 36,
          "maxLength": 36,
          "title": "Workspace ID"
        },
        "description": "Unique identifier for the workspace",
        "example": "9700b29a-b475-4958-be43-38a03c5c741f"
      },
      "collection_name": {
        "name": "collection_name",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "string",
          "maxLength": 128,
          "title": "Collection Name"
        },
        "description": "Name of the collection",
        "example": "en_us"
      }
    },
    "schemas": {
      "StandardPageLimit": {
        "type": "integer",
        "format": "int32",
        "maximum": 100,
        "minimum": 1,
        "default": 20,
        "title": "Standard Page Limit",
        "description": "Standard maximum number of items to return in a page, reusable across multiple endpoints"
      },
      "CollectionName": {
        "type": "string",
        "format": "string",
        "maxLength": 64,
        "minLength": 1,
        "title": "Collection Identifier",
        "description": "Unique identifier for portable references across environments",
        "examples": [
          "winter_2025",
          "en_us",
          "2023-summer"
        ]
      },
      "CollectionDescription": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 1024,
            "minLength": 0,
            "format": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Collection Description",
        "description": "Optional detailed description of the collection's purpose and contents",
        "examples": [
          "Products for the Winter 2025 season",
          "English language product catalog for US market",
          "Campaign assets for Summer 2023 launch"
        ]
      },
      "CollectionDisplayName": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 256,
            "minLength": 1,
            "format": "string"
          },
          {
            "type": "null"
          }
        ],
        "title": "Collection Display Name",
        "description": "Human-readable name for the collection",
        "examples": [
          "Winter 2025 Collection",
          "US English Catalog",
          "Summer 2023 Campaign"
        ]
      },
      "CollectionItemTypeEntry": {
        "type": "object",
        "title": "CollectionItemTypeEntry",
        "description": "Defines an item type and its supported relationships within a collection",
        "properties": {
          "type": {
            "type": "string",
            "format": "string",
            "title": "Item Type Name",
            "description": "The name of the item type. Currently only 'product' is supported.",
            "example": "product",
            "maxLength": 50
          },
          "relationships": {
            "type": "array",
            "title": "Relationships",
            "description": "List of relationships this item type supports. Values must be unique and currently only 'variant' is supported.",
            "items": {
              "type": "string",
              "format": "string",
              "maxLength": 50
            },
            "uniqueItems": true,
            "example": [
              "variant"
            ],
            "maxItems": 1,
            "default": []
          }
        },
        "required": [
          "type"
        ]
      },
      "CollectionItemTypes": {
        "type": "array",
        "title": "CollectionItemTypes",
        "description": "List of item types supported in this collection",
        "items": {
          "$ref": "#/components/schemas/CollectionItemTypeEntry"
        },
        "minItems": 1,
        "maxItems": 50,
        "uniqueItems": true,
        "example": [
          {
            "type": "product",
            "relationships": [
              "variant"
            ]
          }
        ]
      },
      "ResourcePath": {
        "type": "string",
        "format": "string",
        "maxLength": 2048,
        "title": "Resource Path",
        "description": "Fully qualified resource path following a hierarchical structure that uniquely identifies the resource and its position in the resource hierarchy",
        "examples": [
          "/bloomreach/organization/org_123/instances/cvy/workspaces/ws_456/item-collections/en_us",
          "/bloomreach/organization/org_123/instances/cvy/workspaces/ws_456/item-collections/en_us/item-types/product/families/main/records/rec123",
          "/bloomreach/organization/org_123/instances/cvy/workspaces/ws_456/item-collections/en_us/item-types/product/items/itm456"
        ]
      },
      "ResourceParent": {
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "format": "string",
            "title": "Parent ID",
            "description": "Core identifier for the parent resource. This may be a system-generated identifier (for example a workspace ID) or a named identifier value (for example an item collection name).",
            "example": "9700b29a-b475-4958-be43-38a03c5c741f"
          },
          "scope": {
            "type": "string",
            "format": "string",
            "maxLength": 64,
            "title": "Parent Scope",
            "description": "Scope of the parent resource (core types: workspace, item-collection, but extensible)",
            "examples": [
              "workspace",
              "item-collection"
            ]
          }
        },
        "type": "object",
        "required": [
          "id",
          "scope"
        ],
        "description": "Reference to a parent resource",
        "examples": [
          {
            "id": "9700b29a-b475-4958-be43-38a03c5c741f",
            "scope": "workspace"
          },
          {
            "id": "en_us",
            "scope": "item-collection"
          }
        ]
      },
      "Actor": {
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 64,
            "minLength": 1,
            "format": "string",
            "title": "Actor ID",
            "description": "Unique identifier for the actor",
            "examples": [
              "user123",
              "api456",
              "system789"
            ]
          },
          "type": {
            "type": "string",
            "format": "string",
            "maxLength": 64,
            "title": "Actor Type",
            "description": "Type of actor (core types: api, user, system, but extensible)",
            "examples": [
              "api",
              "user",
              "system",
              "integration",
              "service"
            ]
          },
          "display_name": {
            "type": "string",
            "maxLength": 128,
            "minLength": 1,
            "format": "string",
            "title": "Actor Display Name",
            "description": "Human-readable name of the actor for display in UI",
            "examples": [
              "John Smith",
              "External API Client",
              "System Process"
            ]
          }
        },
        "type": [
          "object",
          "null"
        ],
        "required": [
          "id",
          "type",
          "display_name"
        ],
        "title": "Actor",
        "description": "Represents an entity that performed an action",
        "examples": [
          {
            "id": "api456",
            "type": "api",
            "display_name": "External API Client"
          },
          {
            "id": "user123",
            "type": "user",
            "display_name": "John Smith"
          },
          {
            "id": "system789",
            "type": "system",
            "display_name": "System Process"
          },
          null
        ]
      },
      "ResourceMeta": {
        "properties": {
          "created_at": {
            "type": "string",
            "format": "date-time",
            "maxLength": 64,
            "title": "Created At",
            "description": "Timestamp when the resource was created",
            "examples": [
              "2025-03-12T23:15:01.123456Z"
            ]
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "maxLength": 64,
            "title": "Updated At",
            "description": "Timestamp when the resource was last updated",
            "examples": [
              "2025-03-12T23:15:01.123456Z",
              null
            ]
          },
          "created_by": {
            "$ref": "#/components/schemas/Actor",
            "description": "Actor who created the resource",
            "summary": "Reference to the actor who created the resource"
          },
          "updated_by": {
            "$ref": "#/components/schemas/Actor",
            "description": "Actor who last updated the resource",
            "summary": "Reference to the actor who last updated the resource"
          }
        },
        "type": "object",
        "required": [
          "created_at",
          "updated_at",
          "created_by",
          "updated_by"
        ],
        "title": "Resource-Level Metadata",
        "description": "Resource lifecycle metadata containing creation, update, and actor information",
        "examples": [
          {
            "created_at": "2025-03-12T23:15:01.123456Z",
            "updated_at": "2025-03-12T23:15:01.123456Z",
            "created_by": {
              "id": "api456",
              "type": "api",
              "display_name": "External API Client"
            },
            "updated_by": {
              "id": "api456",
              "type": "api",
              "display_name": "External API Client"
            }
          },
          {
            "created_at": "2025-03-12T23:15:01.123456Z",
            "updated_at": "2025-03-13T10:45:23.789012Z",
            "created_by": {
              "id": "user123",
              "type": "user",
              "display_name": "John Smith"
            },
            "updated_by": {
              "id": "system789",
              "type": "system",
              "display_name": "System Process"
            }
          }
        ]
      },
      "ItemCollection": {
        "properties": {
          "name": {
            "$ref": "#/components/schemas/CollectionName"
          },
          "description": {
            "$ref": "#/components/schemas/CollectionDescription"
          },
          "display_name": {
            "$ref": "#/components/schemas/CollectionDisplayName"
          },
          "item_types": {
            "$ref": "#/components/schemas/CollectionItemTypes"
          },
          "resource_path": {
            "$ref": "#/components/schemas/ResourcePath"
          },
          "parent": {
            "$ref": "#/components/schemas/ResourceParent",
            "description": "Parent resource information"
          },
          "meta": {
            "$ref": "#/components/schemas/ResourceMeta",
            "description": "Resource metadata"
          }
        },
        "type": "object",
        "required": [
          "name",
          "display_name",
          "resource_path",
          "parent",
          "meta",
          "item_types"
        ],
        "title": "ItemCollection",
        "description": "Item Collection model representing a persisted collection\n\nExtends the base model with system-managed fields like name (the public identifier),\nparent reference, and metadata.",
        "example": {
          "name": "en_us",
          "description": "Product data for site.com/en/us",
          "display_name": "site.com/en/us items",
          "item_types": [
            {
              "type": "product",
              "relationships": [
                "variant"
              ]
            }
          ],
          "resource_path": "/bloomreach/organization/org_123/instances/cvy/workspaces/ws_456/item-collections/en_us",
          "parent": {
            "id": "9700b29a-b475-4958-be43-38a03c5c741f",
            "scope": "workspace"
          },
          "meta": {
            "created_at": "2025-03-12T23:15:01.123456Z",
            "updated_at": "2025-03-12T23:15:01.123456Z",
            "created_by": {
              "id": "api456",
              "type": "api",
              "display_name": "External API Client"
            },
            "updated_by": {
              "id": "api456",
              "type": "api",
              "display_name": "External API Client"
            }
          }
        }
      },
      "Detail": {
        "properties": {
          "type": {
            "type": "string",
            "format": "string",
            "maxLength": 128,
            "title": "Detail Type",
            "description": "Unique error identifier prefixed with bloomreach/datahub/<general_classification>/<specific-error-short-name>",
            "examples": [
              "bloomreach/datahub/validation/invalid-format",
              "bloomreach/datahub/security/insufficient-permissions",
              "bloomreach/datahub/validation/missing-required-field"
            ]
          },
          "title": {
            "type": "string",
            "maxLength": 128,
            "format": "string",
            "title": "Detail Title",
            "description": "Short human-readable description of the issue",
            "examples": [
              "Invalid Format",
              "Resource Not Found",
              "Insufficient Permissions",
              "Missing Required Field"
            ]
          },
          "detail": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 4096,
                "format": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Detail Message",
            "description": "Optional detailed explanation of the issue with specifics",
            "examples": [
              "Field 'name' must match pattern '^[a-z0-9_-]+$'",
              "Collection with ID '123' not found",
              "The 'name' field is required but was not provided in the request"
            ]
          },
          "severity": {
            "type": "string",
            "format": "string",
            "maxLength": 32,
            "title": "Detail Severity",
            "description": "Severity level of the detail",
            "examples": [
              "info",
              "warning",
              "error"
            ]
          },
          "status_code": {
            "type": "integer",
            "format": "int32",
            "minimum": 100,
            "maximum": 599,
            "title": "HTTP Status Code",
            "description": "HTTP status code associated with this detail",
            "examples": [
              400,
              401,
              403,
              404,
              422,
              500
            ]
          }
        },
        "type": "object",
        "required": [
          "type",
          "title",
          "severity",
          "status_code"
        ],
        "title": "Detail",
        "description": "Detail object following RFC 9457 format"
      },
      "Details": {
        "items": {
          "$ref": "#/components/schemas/Detail"
        },
        "type": "array",
        "maxItems": 100,
        "title": "Detail Messages",
        "description": "Error/warning/info details following RFC 9457 format",
        "example": []
      },
      "ResponseMeta": {
        "type": "object",
        "title": "Response-Level Metadata",
        "description": "Response envelope metadata containing pagination and response-level information",
        "properties": {
          "limit": {
            "$ref": "#/components/schemas/StandardPageLimit",
            "description": "The effective page size used for this response"
          },
          "next": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "URL to retrieve the next page of results, if available"
          },
          "prev": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "URL to retrieve the previous page of results, if available"
          }
        },
        "example": {}
      },
      "ResponseSuccessIndicator": {
        "type": "boolean",
        "title": "Success Flag",
        "description": "Indicates whether the operation was successful",
        "default": true,
        "examples": [
          true,
          false
        ]
      }
    },
    "responses": {
      "ErrorResponse": {
        "description": "Standard error response format for normal application-level failures. In rare edge cases, such as malformed HTTP requests rejected before normal request handling completes, the API may return a more generic fallback error payload.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            },
            "example": {}
          }
        }
      },
      "RateLimitedResponse": {
        "description": "Response format for rate limiting errors (429)",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            },
            "example": {}
          }
        }
      }
    },
    "headers": {
      "Retry-After": {
        "description": "The time in seconds to wait before making another request after receiving a 429 response",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 86400
        }
      }
    },
    "examples": {
      "UpdateCollectionFullObject": {
        "summary": "Complete collection object",
        "description": "Update with a complete collection object. Only the description, display_name, and item_types fields will be updated.",
        "value": {
          "data": {
            "name": "en_us",
            "display_name": "Updated site.com/en/us items",
            "description": "Updated product data for site.com/en/us",
            "item_types": [
              {
                "type": "product",
                "relationships": [
                  "variant"
                ]
              }
            ],
            "resource_path": "/bloomreach/organization/org_123/instances/cvy/workspaces/ws_456/item-collections/en_us",
            "parent": {
              "id": "9700b29a-b475-4958-be43-38a03c5c741f",
              "scope": "workspace"
            },
            "meta": {
              "created_at": "2025-03-12T23:15:01.123456Z",
              "updated_at": "2025-03-13T14:22:05.654321Z",
              "created_by": {
                "id": "api456",
                "type": "api",
                "display_name": "External API Client"
              },
              "updated_by": {
                "id": "api456",
                "type": "api",
                "display_name": "External API Client"
              }
            }
          },
          "success": true,
          "details": [],
          "meta": {}
        }
      },
      "UpdateCollectionItemTypes": {
        "summary": "Update item types",
        "description": "Update the collection's supported item types and their relationships.",
        "value": {
          "data": {
            "name": "en_us",
            "display_name": "site.com/en/us items",
            "description": "Product data for site.com/en/us",
            "item_types": [
              {
                "type": "product",
                "relationships": [
                  "variant"
                ]
              }
            ],
            "resource_path": "/bloomreach/organization/org_123/instances/cvy/workspaces/ws_456/item-collections/en_us",
            "parent": {
              "id": "9700b29a-b475-4958-be43-38a03c5c741f",
              "scope": "workspace"
            },
            "meta": {
              "created_at": "2025-03-12T23:15:01.123456Z",
              "updated_at": "2025-03-13T14:22:05.654321Z",
              "created_by": {
                "id": "api456",
                "type": "api",
                "display_name": "External API Client"
              },
              "updated_by": {
                "id": "api456",
                "type": "api",
                "display_name": "External API Client"
              }
            }
          },
          "success": true,
          "details": [],
          "meta": {}
        }
      }
    }
  }
}
```