--- updatedAt: 2026-09-09T09:34:23.000Z agentTools: siteIndex: https://documentation.bloomreach.com/llms.txt projectIndex: https://documentation.bloomreach.com/content/llms.txt --- # Create or update a component within a component group # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Site Management API", "description": "The Site Management API enables developers to manage channel configurations through a set of endpoints for operations on channels, layouts, component groups, routes, and menus.", "version": "1.0.0" }, "externalDocs": { "description": "See official Bloomreach documentation", "url": "https://documentation.bloomreach.com/content/reference/site-management-api" }, "servers": [ { "url": "https://developers.bloomreach.io/management/site/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Channel Component Operations", "externalDocs": { "description": "See", "url": "https://documentation.bloomreach.com/developers/concepts/channels-and-pages-concepts.html#scroll_component" } } ], "paths": { "/channels/{channel_id}/component_groups/{group_name}/components/{component_name}": { "put": { "tags": [ "Channel Component Operations" ], "summary": "Create or update a component within a component group", "operationId": "putChannelCatalogGroupComponent", "parameters": [ { "name": "X-Resource-Version", "in": "header", "description": "Resource's version. Must be used in any subsequent update requests of this resource. Can be obtained when GETting the resource", "required": false, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "433cc90445d29c2356e385b9efe548b19ed86739f27eb7958a81847b9d8517c2" }, { "name": "channel_id", "in": "path", "description": "Channel id. Optionally includes the project id, separated by a dash: mychannel-branchId", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "brxsaas-vIUy9" }, { "name": "group_name", "in": "path", "description": "Name of group", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "sample-group" }, { "name": "component_name", "in": "path", "description": "Name of component", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "video" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDefinition" }, "example": { "id": "sample-group/video", "extends": "base/component", "hidden": false, "system": false, "xtype": null, "ctype": "Video", "contentType": "brxsaas:titleandtext", "label": "Video", "icon": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNzYiIHZpZXdCb3g9IjAgMCAyNCAyNCIgd2lkdGg9Ijc2Ij48cGF0aCBkPSJNMCAwaDI0djI0SDBWMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMjEgM0gzYy0xLjExIDAtMiAuODktMiAydjEyYzAgMS4xLjg5IDIgMiAyaDV2Mmg4di0yaDVjMS4xIDAgMS45OS0uOSAxLjk5LTJMMjMgNWMwLTEuMTEtLjktMi0yLTJ6bTAgMTRIM1Y1aDE4djEyem0tNS02bC03IDRWN3oiIGZpbGw9IiMwMDI4NDAiLz48L3N2Zz4=", "parameters": [ { "name": "url", "valueType": "string", "required": true, "hidden": false, "overlay": false, "defaultValue": "", "displayName": null, "system": false, "config": null }, { "name": "document", "valueType": "string", "required": true, "hidden": false, "overlay": false, "defaultValue": "", "displayName": "A document", "system": false, "config": { "pickerConfiguration": "cms-pickers/documents-only", "pickerInitialPath": "banners", "pickerRememberLastVisited": true, "pickerSelectableNodeTypes": [ "banner" ], "relative": true, "type": "contentpath" } } ], "fieldGroups": [ { "name": "param-group-key", "displayName": "Param group key", "parameters": [ "url" ] } ] } } } }, "responses": { "200": { "description": "OK", "headers": { "X-Resource-Version": { "description": "Resource's version. Must be used in any subsequent update requests of this resource", "style": "simple", "explode": false, "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDefinition" }, "example": { "id": "sample-group/video", "extends": "base/component", "hidden": false, "system": false, "xtype": null, "ctype": "Video", "contentType": "brxsaas:titleandtext", "label": "Video", "icon": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNzYiIHZpZXdCb3g9IjAgMCAyNCAyNCIgd2lkdGg9Ijc2Ij48cGF0aCBkPSJNMCAwaDI0djI0SDBWMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMjEgM0gzYy0xLjExIDAtMiAuODktMiAydjEyYzAgMS4xLjg5IDIgMiAyaDV2Mmg4di0yaDVjMS4xIDAgMS45OS0uOSAxLjk5LTJMMjMgNWMwLTEuMTEtLjktMi0yLTJ6bTAgMTRIM1Y1aDE4djEyem0tNS02bC03IDRWN3oiIGZpbGw9IiMwMDI4NDAiLz48L3N2Zz4=", "parameters": [ { "name": "url", "valueType": "string", "required": true, "hidden": false, "overlay": false, "defaultValue": "", "displayName": null, "system": false, "config": null }, { "name": "document", "valueType": "string", "required": true, "hidden": false, "overlay": false, "defaultValue": "", "displayName": "A document", "system": false, "config": { "pickerConfiguration": "cms-pickers/documents-only", "pickerInitialPath": "banners", "pickerRememberLastVisited": true, "pickerSelectableNodeTypes": [ "banner" ], "relative": true, "type": "contentpath" } } ], "fieldGroups": [ { "name": "param-group-key", "displayName": "Param group key", "parameters": [ "url" ] } ] } } } }, "201": { "description": "Created", "headers": { "X-Resource-Version": { "description": "Resource's version. Must be used in any subsequent update requests of this resource", "style": "simple", "explode": false, "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDefinition" }, "example": { "id": "sample-group/video", "extends": "base/component", "hidden": false, "system": false, "xtype": null, "ctype": "Video", "contentType": "brxsaas:titleandtext", "label": "Video", "icon": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iNzYiIHZpZXdCb3g9IjAgMCAyNCAyNCIgd2lkdGg9Ijc2Ij48cGF0aCBkPSJNMCAwaDI0djI0SDBWMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMjEgM0gzYy0xLjExIDAtMiAuODktMiAydjEyYzAgMS4xLjg5IDIgMiAyaDV2Mmg4di0yaDVjMS4xIDAgMS45OS0uOSAxLjk5LTJMMjMgNWMwLTEuMTEtLjktMi0yLTJ6bTAgMTRIM1Y1aDE4djEyem0tNS02bC03IDRWN3oiIGZpbGw9IiMwMDI4NDAiLz48L3N2Zz4=", "parameters": [ { "name": "url", "valueType": "string", "required": true, "hidden": false, "overlay": false, "defaultValue": "", "displayName": null, "system": false, "config": null }, { "name": "document", "valueType": "string", "required": true, "hidden": false, "overlay": false, "defaultValue": "", "displayName": "A document", "system": false, "config": { "pickerConfiguration": "cms-pickers/documents-only", "pickerInitialPath": "banners", "pickerRememberLastVisited": true, "pickerSelectableNodeTypes": [ "banner" ], "relative": true, "type": "contentpath" } } ], "fieldGroups": [ { "name": "param-group-key", "displayName": "Param group key", "parameters": [ "url" ] } ] } } } }, "403": { "description": "Forbidden" } } } } }, "components": { "schemas": { "ComponentDefinition": { "required": [ "extends", "id" ], "type": "object", "properties": { "id": { "type": "string", "description": "identifier of this component definition: {group}/{name}" }, "extends": { "type": "string", "description": "{group}/{name} id of the component definition this definition extends from" }, "hidden": { "type": "boolean", "description": "indicator if this component definition is configurable in the ChannelManager UI" }, "system": { "type": "boolean", "description": "indicator if this a protected (system) component definition; if true, implies hidden is true" }, "xtype": { "type": "string", "description": "frontend layout type" }, "ctype": { "type": "string", "description": "frontend component type" }, "contentType": { "type": "string", "description": "contentType for cases where the component should also create content: when putting, the contentType must be an existing document compound type, otherwise the request is not executed. The value for the contentType may optionally include the namespace prefix; this is only required in case the type is in a namespace other than 'brxsaas', eg mynamespace:titleandtext" }, "label": { "type": "string", "description": "default display name of this component definition in the ChannelManager UI" }, "icon": { "type": "string", "description": "base64 representation of the icon for this component definition in the ChannelManager UI" }, "parameters": { "type": "array", "description": "custom (residual) or customized (overlaying) parameters for this component definition. Parameters with config type 'imagesetpath' are not allowed", "items": { "$ref": "#/components/schemas/Parameter" } }, "fieldGroups": { "type": "array", "description": "field groups", "items": { "$ref": "#/components/schemas/FieldGroup" } } }, "externalDocs": { "description": "See", "url": "https://documentation.bloomreach.com/developers/concepts/channels-and-pages-concepts.html#scroll_component" } }, "FieldGroup": { "type": "object", "properties": { "name": { "type": "string", "description": "Field Group Name" }, "displayName": { "type": "string", "description": "Field Group Display Name" }, "parameters": { "type": "array", "description": "Field Group Parameters", "items": { "type": "string", "description": "Field Group Parameters" } } } }, "KeyLabel": { "required": [ "key", "label" ], "type": "object", "properties": { "key": { "type": "string", "description": "key validation of the field. Expects a string value" }, "label": { "type": "string", "description": "label validation of the field. Expects a string value" } }, "description": "Expects an array of key-label values." }, "Parameter": { "required": [ "name", "valueType" ], "type": "object", "properties": { "name": { "type": "string" }, "valueType": { "type": "string", "enum": [ "string", "calendar", "boolean", "integer", "number" ] }, "required": { "type": "boolean" }, "hidden": { "type": "boolean" }, "overlay": { "type": "boolean" }, "defaultValue": { "type": "object" }, "displayName": { "type": "string" }, "system": { "type": "boolean", "description": "System readonly parameter" }, "config": { "$ref": "#/components/schemas/ParameterConfig" } } }, "ParameterConfig": { "required": [ "type" ], "type": "object", "properties": { "type": { "type": "string", "description": "the type of this config field", "readOnly": true, "enum": [ "contentpath", "dropdown", "imagesetpath" ] } }, "description": "Field Config, or null if this parameter is neither of the types below. The config type 'imagesetpath' cannot be used with component parameters but only with channel parameters", "discriminator": { "propertyName": "type", "mapping": { "contentpath": "#/components/schemas/ParameterContentPath", "dropdown": "#/components/schemas/ParameterDropdown", "imagesetpath": "#/components/schemas/ParameterImageSetPath" } }, "oneOf": [ { "$ref": "#/components/schemas/ParameterContentPath" }, { "$ref": "#/components/schemas/ParameterDropdown" }, { "$ref": "#/components/schemas/ParameterImageSetPath" } ] }, "ParameterContentPath": { "required": [ "type" ], "type": "object", "properties": { "pickerConfiguration": { "type": "string" }, "pickerInitialPath": { "type": "string" }, "pickerRememberLastVisited": { "type": "boolean" }, "pickerSelectableNodeTypes": { "type": "array", "items": { "type": "string" } }, "relative": { "type": "boolean" }, "pickerRootPath": { "type": "string" }, "enableUpload": { "type": "boolean" }, "type": { "type": "string", "description": "the type of this config field", "readOnly": true, "enum": [ "contentpath", "dropdown", "imagesetpath" ] } }, "description": "This config type is used when a document picker is needed in the CMS UI. See [Define Configuration Parameters for Components](https://documentation.bloomreach.com/content/docs/define-configuration-parameters-for-components)" }, "ParameterDropdown": { "required": [ "sourceId", "type", "value" ], "type": "object", "properties": { "value": { "type": "array", "items": { "type": "string" } }, "structuredValues": { "type": "array", "description": "Expects an array of key-label values.", "items": { "$ref": "#/components/schemas/KeyLabel" } }, "valueListProvider": { "type": "string" }, "sourceId": { "type": "string" }, "type": { "type": "string", "description": "the type of this config field", "readOnly": true, "enum": [ "contentpath", "dropdown", "imagesetpath" ] } }, "description": "This config type is used when a dropdown list is needed in the CMS UI. See [Define Configuration Parameters for Components](https://documentation.bloomreach.com/content/docs/define-configuration-parameters-for-components)" }, "ParameterImageSetPath": { "required": [ "type" ], "type": "object", "properties": { "pickerConfiguration": { "type": "string" }, "pickerInitialPath": { "type": "string" }, "pickerRememberLastVisited": { "type": "boolean" }, "pickerSelectableNodeTypes": { "type": "array", "items": { "type": "string" } }, "previewVariant": { "type": "string" }, "enableUpload": { "type": "boolean" }, "type": { "type": "string", "description": "the type of this config field", "readOnly": true, "enum": [ "contentpath", "dropdown", "imagesetpath" ] } }, "description": "This config type is used when an image picker is needed in the CMS UI" } }, "securitySchemes": { "bearerAuth": { "type": "apiKey", "name": "x-auth-token", "in": "header" } } } } ```