Item collection configuration tools

get_item_collection_configuration: Get a collection's attribute schema, identifiers, and destinations.
update_item_collection_configuration: Apply a change-list to a collection's configuration.
compare_item_collection_configurations: Diff a candidate configuration against a stored version.
validate_item_collection_attribute: Check one attribute definition before you write it.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Bloomreach dashboard, actions your users or agents take with these tools can have a substantial impact on your item collection schema, its destination pipelines, and the reindex jobs they trigger. Configuration writes are audited with a before-state snapshot, but there is no automatic rollback, so review every change and confirm the target before applying it.

get_item_collection_configuration

Gets the schema configuration for a Data hub item collection. The response covers the custom attribute definitions, the identifier fields, the destination pipeline configurations, and an etag version hash. Read it before you query records or items, so you know what fields the collection defines rather than guessing from the data.

This tool has a second job: it supplies the etag that update_item_collection_configuration requires as expected_hash. Read the configuration immediately before every write, since a hash that another change has superseded is rejected.

By default you get the LATEST version. Pass a configuration_id version hash to fetch a historical version instead. That's how you compare the schema a past job ran with against the current one, because each job record from search_datahub_jobs carries the configuration_id that was active when it ran. A collection with no configuration yet returns an error, as does a configuration_id that isn't in the version history. Timestamps here are ISO 8601 strings, unlike the Unix epoch floats that search_item_collections returns. This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`workspace_id`	`str`	Yes	The workspace ID returned by `list_workspaces`.
`collection_name`	`str`	Yes	The collection name returned by `search_item_collections`.
`configuration_id`	`str`	No	The configuration version to fetch. Defaults to `LATEST`. Pass a version hash to fetch a historical version, such as the `configuration_id` a past job ran with.

Response parameters

The tool returns a CollectionConfigurationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CollectionConfiguration \| null`	The requested configuration, `LATEST` by default.
`details`	`list[Any]`	Additional detail messages from the API.
`error`	`str \| null`	Error message if the request failed.

The CollectionConfiguration object has the following fields:

Field	Type	Description
`created`	`str \| null`	ISO 8601 timestamp of when the configuration was created.
`created_by_id`	`str \| null`	The ID of the user or service that created the configuration.
`edited`	`str \| null`	ISO 8601 timestamp of when the configuration was last edited.
`edited_by_id`	`str \| null`	The ID of the user or service that last edited the configuration.
`etag`	`str \| null`	The configuration version hash. Pass it as `expected_hash` on `update_item_collection_configuration`.
`collection_schema`	`CollectionConfigurationSchema \| null`	The attribute and identifier schema definitions. The API field name is `schema`.
`destinations`	`list[dict[str, Any]]`	The destination pipeline configurations.

The CollectionConfigurationSchema object has the following fields:

Field	Type	Description
`attributes`	`list[dict[str, Any]]`	The custom attribute definitions.
`identifiers`	`list[dict[str, Any]]`	The identifier field definitions.

update_item_collection_configuration

Applies a change-list to an item collection's configuration. Each entry names an action of add, modify, or remove, an object_type of schema.attribute, schema.identifier, or destination, and the compound keys that identify the target object. Use it to add a custom attribute, repoint a destination, or retire a field that your feed no longer sends.

The tool uses optimistic concurrency. Call get_item_collection_configuration immediately before writing and pass data.etag as expected_hash. A stale hash returns an error, which means someone or something else changed the configuration between your read and your write, so re-read and rebuild the change-list. The tool also pre-validates keys locally: modify or remove on a key that isn't in the current configuration is rejected, as is add on a key that already exists. That check exists because the backend would otherwise accept the request and silently do nothing.

Two read tools pair with this one. Run validate_item_collection_attribute on each attribute new_value before you write, and use compare_item_collection_configurations to build or review the change-list. Set on_success_trigger if you want a pipeline such as update-items to run after the write succeeds, and expect the response details to mention any downstream job the platform rate-limited. Changes here alter the live schema and destinations and can trigger reindex jobs, so confirm the collection with the user first. A blank workspace_id is rejected before any call is made. Writes are audited with a full before-state snapshot and throttled to one call every five seconds and 10 per minute. This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`workspace_id`	`str`	Yes	The workspace ID returned by `list_workspaces`.
`collection_name`	`str \| null`	Yes	The name of the collection to update. Confirm the exact name with the user. Use `search_item_collections` to list the options.
`expected_hash`	`str \| null`	Yes	The configuration version hash from `data.etag` on `get_item_collection_configuration`. Read it immediately before calling.
`changes`	`list[ConfigurationChange]`	Yes	The ordered change-list to apply.
`on_success_trigger`	`list[str] \| null`	No	Pipelines to trigger after a successful write, such as `update-items`.

Each ConfigurationChange object has the following fields:

Field	Type	Description
`action`	`str`	The change action: `add`, `modify`, or `remove`.
`object_type`	`str`	The object type: `schema.attribute`, `schema.identifier`, or `destination`.
`keys`	`dict`	The compound key identifying the object. Attributes use `name`, `item_type`, `family`, and `level`. Identifiers use `item_type`, `family`, and `level`. Destinations use `name` and `type`.
`new_value`	`dict \| null`	The object definition for `add` and `modify`. Omit it for `remove`.

Response parameters

The tool returns a CollectionConfigurationWriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the write succeeded.
`data`	`CollectionConfiguration \| null`	The updated configuration, including the new `etag` and any `jobs_triggered`.
`details`	`list`	Additional detail messages from the API, such as downstream jobs that were rate-limited.
`error`	`str \| null`	Error message if the write failed.

compare_item_collection_configurations

Compares a candidate configuration against a stored base version and returns the difference as a change-list. The change-list uses the same ConfigurationChange shape that update_item_collection_configuration accepts, so you can review a diff and then apply the entries you want. Nothing is written.

Set the base version with configuration_id, which defaults to LATEST. Describe the candidate one of two ways. Pass compare_schema and compare_destinations together to compare against a configuration you've assembled inline, or pass compare_collection_name and compare_configuration_id together to compare against another stored version. Reference mode works across collections in the same workspace, which is how you check whether a staging collection and a production collection have drifted apart.

The backend may add display fields such as display_type and display_name to each change, and compare output also carries original_value. Only action, object_type, keys, and new_value matter when you pass the changes on to a write. Validate any attribute changes with validate_item_collection_attribute before you apply them. This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`workspace_id`	`str`	Yes	The workspace ID returned by `list_workspaces`.
`collection_name`	`str`	Yes	The collection name that holds the base configuration.
`configuration_id`	`str`	No	The base configuration version. Defaults to `LATEST`. Pass a version hash for a historical base.
`compare_schema`	`dict[str, Any] \| null`	No	The inline candidate schema, with `attributes` and `identifiers`. Requires `compare_destinations`.
`compare_destinations`	`list[dict[str, Any]] \| null`	No	The inline candidate destinations list. Requires `compare_schema`.
`compare_collection_name`	`str \| null`	No	The collection name holding a stored candidate configuration. Requires `compare_configuration_id`.
`compare_configuration_id`	`str \| null`	No	The configuration version hash, or `LATEST`, for the stored candidate. Requires `compare_collection_name`.

Provide either the inline pair, compare_schema and compare_destinations, or the reference pair, compare_collection_name and compare_configuration_id.

Response parameters

The tool returns a ConfigurationCompareResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the comparison succeeded.
`data`	`ConfigurationCompareData \| null`	The diff change-list when the call succeeded.
`error`	`str \| null`	Error message if the comparison failed.

The ConfigurationCompareData object has the following fields:

Field	Type	Description
`changes`	`list[ConfigurationChange]`	The changes from base to candidate, in the same shape as the `changes` parameter on `update_item_collection_configuration`.

validate_item_collection_attribute

Checks a single attribute definition without writing anything. Call it when you want to add or modify a custom attribute and need to catch a malformed definition before it reaches the configuration. A success value of true means the definition is valid, and false comes back with an error message explaining what to fix.

The recommended sequence is to read the current schema with get_item_collection_configuration, validate the proposed attribute here, then include it as an add or modify change on update_item_collection_configuration. Re-read the configuration immediately before that write so you pass a current expected_hash.

This tool validates attribute definitions only. Identifier and destination changes have no validation endpoint, so those are checked when you apply them on the write tool. Use it before every attribute add or modify where the shape is new or uncertain. This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`workspace_id`	`str`	Yes	The workspace ID returned by `list_workspaces`.
`collection_name`	`str`	Yes	The collection name returned by `search_item_collections`.
`attribute`	`dict[str, Any]`	Yes	The attribute definition to validate, for example `{'name': 'title', 'item_type': 'product', 'family': 'main', 'level': 'parent', 'data_type': 'String'}`.

Response parameters

The tool returns a ConfigurationValidateResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the attribute definition is valid.
`error`	`str \| null`	The validation or request error message when it isn't valid.