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 superseded by another change is rejected.

Configuration is scoped to a single item type. Omit item_type to get the product type's configuration, which is the default and what every collection has. Use the same item_type on this tool and on update_item_collection_configuration, so the etag you read matches the configuration you're about to write.

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.

🚧
Warning
A collection with no configuration yet returns an error, as does a configuration_id that isn't in the version history.

📘
Note
An item type other than product reports its Marketing destinations under catalogs rather than lookups. 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.
`item_type`	`str \| null`	No	The item type whose configuration to fetch. Omit to get the `product` type's configuration.

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`	`dict[str, Any]`	The destination pipeline configurations, grouped by platform as `{engagement: [...], discovery: [...]}`. An older flat list is grouped into this shape automatically.

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. Read the configuration for the same item_type you're about to write, so the hash matches. 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.

🚧
Warning
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.
`item_type`	`str \| null`	No	The item type whose configuration to update. Omit to target the `product` type.
`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`, `family`, and `level`. Identifiers use `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, and set the base item type with item_type, which defaults to product.

Describe the candidate one of two ways. The two modes are mutually exclusive:

Pass compare_schema and compare_destinations together to compare against a configuration you've assembled inline.
Pass compare_configuration_id on its own to compare against a stored version.

Both modes also require compare_reference_collection_name and compare_reference_item_type, which name the reference the comparison is sent against. Because you name the reference collection yourself, the comparison 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 the 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.

🚧
Warning
Destination differences are reported for visibility only, since they don't come back in a form update_item_collection_configuration can apply. Make destination changes through the configuration tools directly rather than through a compare-then-apply flow.

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.
`compare_reference_collection_name`	`str \| null`	Yes	The reference collection name to send in the comparison. Required in both candidate modes.
`compare_reference_item_type`	`str \| null`	Yes	The reference item type name to send in the comparison. Required in both candidate modes.
`configuration_id`	`str`	No	The base configuration version. Defaults to `LATEST`. Pass a version hash for a historical base.
`item_type`	`str \| null`	No	The item type whose configuration to compare against. Omit to target `product`.
`compare_schema`	`dict[str, Any] \| null`	No	The inline candidate schema, with `attributes` and `identifiers`. Requires `compare_destinations`.
`compare_destinations`	`dict[str, Any] \| null`	No	The inline candidate destinations, grouped by platform, such as `{engagement: [...], discovery: [...]}`. Requires `compare_schema`.
`compare_configuration_id`	`str \| null`	No	The configuration version hash, or `LATEST`, for the stored candidate. Mutually exclusive with `compare_schema`.

Provide either the inline pair, compare_schema and compare_destinations, or the stored candidate, 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.

Use it before every attribute add or modify where the shape is new or uncertain.

📘
Note
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.

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', 'family': 'main', 'level': 'parent', 'data_type': 'String'}`.
`item_type`	`str \| null`	No	The item type the attribute belongs to. Omit to validate against the `product` type.

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.