Item collections tools

search_item_collections: List the item collections in a workspace, or fetch one by name.
search_item_collection_fields: List the product fields observed in a collection, or get one field's detail.
search_item_collection_items: List the transformed product items in a collection, or fetch one item or variant.
search_item_collection_records: List the raw product records in a collection, or fetch one record or variant.
create_item_collection: Create a new item collection in a workspace.
update_item_collection_metadata: Update a collection's display name, description, or item types.
delete_item_collection: Permanently delete an item collection and enqueue cleanup of its data.

🚧
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 product data pipelines, catalogs, and recommendations. Updates and deletes are audited with a before-state snapshot, but there is no automatic rollback, so review every change and confirm the exact collection name before applying it.

search_item_collections

Searches the Data hub item collections in a workspace, or fetches one by name. An item collection holds the product data for a workspace: the raw records written by the records-update pipeline, the transformed items that Search and Marketing read, and the schema configuration that connects them. Omit collection_name to list every collection with its name, display name, item types, and audit metadata. Pass collection_name to fetch a single collection's details.

Start here. Almost every other Data hub tool needs a collection_name, and this is the only tool that lists the names available to you. Resolve workspace_id first with list_cloud_organizations and then list_workspaces, and pick a workspace that returns a data_engine_url, since only those workspaces have Data hub enabled. The list endpoint returns every collection in one response, so there's no pagination and no way to narrow the result set server-side. 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`	No	A collection name for a direct lookup, such as `my_products`. Omit to list all collections in the workspace.

Response parameters

The response shape depends on whether you pass collection_name. When you omit it, the tool returns an ItemCollectionsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[ItemCollectionSummary]`	The item collections in this workspace.
`error`	`str \| null`	Error message if the request failed.

When you pass collection_name, the tool returns an ItemCollectionResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`ItemCollectionSummary \| null`	The item collection's details.
`error`	`str \| null`	Error message if the request failed.

The ItemCollectionSummary object has the following fields:

Field	Type	Description
`id`	`str`	The collection's unique ID.
`name`	`str`	The machine-readable collection name, such as `my_products`.
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	The collection description.
`workspace_id`	`str`	The workspace this collection belongs to.
`item_types`	`list[ItemCollectionItemType]`	The item type definitions and their relationship types.
`created`	`float \| null`	Unix timestamp of when the collection was created.
`edited`	`float \| null`	Unix timestamp of when the collection was last edited.
`created_by_id`	`str \| null`	The ID of the user or service that created the collection.
`created_by_display_name`	`str \| null`	The display name of the creator.
`created_by_type`	`str \| null`	The creator's actor type, such as `api` or `user`.
`edited_by_id`	`str \| null`	The ID of the user or service that last edited the collection.
`edited_by_display_name`	`str \| null`	The display name of the last editor.
`edited_by_type`	`str \| null`	The last editor's actor type, such as `api` or `user`.

The ItemCollectionItemType object has the following fields:

Field	Type	Description
`type`	`str`	The item type name, such as `product`.
`relationships`	`list[str]`	The relationship types this item type supports, such as `variant`.

search_item_collection_fields

Lists the product fields observed in an item collection, or gets one field's full detail. Data hub discovers fields automatically from the records you ingest, so there's no schema to define up front. That makes this tool the fastest way to answer "what fields does this collection actually have, and what do their values look like?" before you write a query or a filter.

The default summary mode returns each field with sample values, aggregate metrics, and the last job that observed it, which is useful for spotting a field that stopped arriving in your feed. Switch to autosuggest mode for a compact list of names, families, and levels. Pass query to filter list results by name prefix, so pr matches price but not brand. Pass field_name instead to get one field's per-job observation history and window statistics, in which case mode and query are ignored. An unknown family returns an empty data array in list mode and an error in detail mode. 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`.
`field_name`	`str \| null`	No	A field name for a direct lookup, such as `brand`. Omit to list all fields in the collection.
`mode`	`str \| null`	No	The list mode, used only when `field_name` is omitted. `summary`, the default, returns full field information with sample values and metrics. `autosuggest` returns a compact list of field names.
`query`	`str \| null`	No	A field name prefix filter for list mode. Returns only fields whose name starts with this string.
`family`	`str \| null`	No	An item-type family filter. Omit to use the server default of `main`. Avoid passing `default`, which isn't a valid family name.
`level`	`str \| null`	No	The field hierarchy level, used only in detail mode. Use `parent` for product-level fields. Omit to use the server default.

Response parameters

The response shape depends on whether you pass field_name. When you omit it, the tool returns a CollectionFieldsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CollectionFieldSummary]`	The fields observed in this item collection.
`error`	`str \| null`	Error message if the request failed.

When you pass field_name, the tool returns a CollectionFieldResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CollectionField \| null`	The field's detail.
`error`	`str \| null`	Error message if the request failed.

The CollectionFieldSummary object, returned in list mode, has the following fields:

Field	Type	Description
`name`	`str`	The field name, such as `brand` or `price`.
`family`	`str`	The item-type family this field belongs to, such as `main`.
`level`	`str`	The field's level in the item hierarchy, such as `parent` or `variant`.
`currently_present`	`bool \| null`	Whether the field appeared in the most recent import job.
`examples`	`list[FieldExample] \| null`	Sample values observed for this field. Summary mode only.
`last_observed_job`	`FieldJobRef \| null`	The most recent job that observed this field. Summary mode only.
`metrics`	`list[FieldMetric] \| null`	Aggregate counters for this field across all jobs. Summary mode only.

The CollectionField object, returned in detail mode, has the following fields:

Field	Type	Description
`name`	`str`	The field name.
`family`	`str`	The item-type family, such as `main`.
`level`	`str`	The field's level, such as `parent` or `variant`.
`currently_present`	`bool \| null`	Whether the field appeared in the most recent import job.
`examples`	`list[FieldExample] \| null`	Sample values observed for this field.
`observations`	`list[FieldObservation] \| null`	The per-job observation history for this field.
`windows`	`list[FieldWindow] \| null`	Job window statistics for this field.

search_item_collection_items

Lists the transformed product items in an item collection, or fetches a single item or variant. Items are the enriched output of the items-update pipeline, so they represent what Search and Marketing actually read. Their attributes and families are structured differently from the raw records that went in, which makes this the right tool for checking what your shoppers see rather than what your feed sent.

Omit item_id to page through items. Pass item_id to fetch one item, or pass both item_id and variant_id to fetch one variant. When item_id is set, limit, page_token, and query are ignored, and passing variant_id without item_id fails validation before any call is made. If this tool returns nothing but search_item_collection_records returns data, the items-update job likely hasn't run yet. Check its status with search_datahub_jobs. Pagination uses the base64-encoded cursor in meta.next_page_token rather than a page number. 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`.
`item_id`	`str \| null`	No	An item ID for a direct lookup, such as `test-prod-001`. Omit to list items. Required when you pass `variant_id`.
`variant_id`	`str \| null`	No	A variant ID within the item, such as `variant-001`. Requires `item_id`. Omit to fetch the parent item only.
`limit`	`int`	No	The number of items to return in list mode. Defaults to `20`, with a maximum of `100`.
`page_token`	`str \| null`	No	The pagination cursor for the next page, taken from `meta.next_page_token` in the previous response. Omit for the first page. List mode only.
`query`	`str \| null`	No	An item ID prefix filter for list mode. Returns only items whose ID starts with this string.

Response parameters

In list mode, when item_id is omitted, the tool returns a ProductItemsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[dict[str, Any]]`	The product item objects. Items are the transformed output of the items-update pipeline, so their attributes and families are structured differently from raw records.
`meta`	`ProductItemsMeta \| null`	Pagination metadata.
`error`	`str \| null`	Error message if the request failed.

The ProductItemsMeta object has the following fields:

Field	Type	Description
`limit`	`int \| null`	The maximum number of items returned per page.
`offset`	`int \| null`	The current page offset.
`next_page_token`	`str \| null`	The cursor for the next page. Pass it as `page_token` on the next call. A `null` value means this is the last page.
`prev_page_token`	`str \| null`	The cursor for the previous page. A `null` value means this is the first page.

When item_id is set and variant_id is omitted, the tool returns a ProductItemResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict[str, Any] \| null`	The product item object, including its attributes, families, metadata, and `variant_ids` when the collection supports variants.
`error`	`str \| null`	Error message if the request failed.

When both item_id and variant_id are set, the tool returns a ProductVariantItemResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict[str, Any] \| null`	The variant item object, including its attributes, families, and parent item metadata.
`error`	`str \| null`	Error message if the request failed.

search_item_collection_records

Lists the raw product records in an item collection, or fetches a single record or variant. Records are the data as written by the records-update pipeline, before the items-update pipeline transforms it. Reach for this tool when you're debugging an ingestion problem and need to see what arrived, rather than what Search and Marketing ended up with.

Record field names depend on the collection's attribute schema, so call get_item_collection_configuration first if you aren't sure what to expect. Omit record_id to page through records, pass record_id for one record, or pass both record_id and variant_id for one variant. When record_id is set, limit, page_token, and query are ignored, and passing variant_id without record_id fails validation before any call is made. Pagination uses the base64-encoded cursor in meta.next_page_token. 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`.
`record_id`	`str \| null`	No	A record ID for a direct lookup, such as `test-prod-001`. Omit to list records. Required when you pass `variant_id`.
`variant_id`	`str \| null`	No	A variant ID within the record, such as `variant-001`. Requires `record_id`. Omit to fetch the parent record only.
`limit`	`int`	No	The number of records to return in list mode. Defaults to `20`, with a maximum of `100`.
`page_token`	`str \| null`	No	The pagination cursor for the next page, taken from `meta.next_page_token` in the previous response. Omit for the first page. List mode only.
`query`	`str \| null`	No	A record ID prefix filter for list mode. Returns only records whose ID starts with this string.
`family`	`str \| null`	No	An item-type family filter. Omit to use the server default of `main`. Avoid passing `default`, which isn't a valid family name.

Response parameters

In list mode, when record_id is omitted, the tool returns a ProductRecordsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[dict[str, Any]]`	The product record objects. Field names depend on the collection's attribute schema, which `get_item_collection_configuration` returns.
`meta`	`ProductRecordsMeta \| null`	Pagination metadata.
`error`	`str \| null`	Error message if the request failed.

The ProductRecordsMeta object has the following fields:

Field	Type	Description
`limit`	`int \| null`	The maximum number of records returned per page.
`offset`	`int \| null`	The current page offset.
`next_page_token`	`str \| null`	The cursor for the next page. Pass it as `page_token` on the next call. A `null` value means this is the last page.
`prev_page_token`	`str \| null`	The cursor for the previous page. A `null` value means this is the first page.

When record_id is set and variant_id is omitted, the tool returns a ProductRecordResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict[str, Any] \| null`	The product record object, including its fields, metadata, and `variant_ids` when the collection supports variants.
`error`	`str \| null`	Error message if the request failed.

When both record_id and variant_id are set, the tool returns a ProductVariantRecordResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict[str, Any] \| null`	The variant record object, including its fields and parent record metadata.
`error`	`str \| null`	Error message if the request failed.

create_item_collection

Creates a new Data hub item collection in a workspace. The collection starts empty, and you attach a schema and destinations afterward with update_item_collection_configuration. Use it when you're setting up a new product data pipeline rather than adjusting an existing one.

The name is machine-readable and must match ^([a-z0-9_-]{1,64})$, so lowercase letters, digits, underscores, and hyphens only. Ask the user for the name rather than generating one, since the collection name is what every other Data hub tool refers to and renaming it later isn't possible. Creation isn't idempotent, so a second call with the same name fails. A blank workspace_id is rejected before any call is made, so resolve the organization and workspace with list_cloud_organizations and list_workspaces first. Write tools are 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`.
`name`	`str \| null`	Yes	The machine-readable collection name, such as `my_products`. Must match `^([a-z0-9_-]{1,64})$`. Ask the user for this value rather than inventing one.
`display_name`	`str \| null`	No	The human-readable display name, 1 to 128 characters. Defaults to `name` when omitted.
`description`	`str \| null`	No	The collection description, up to 1,024 characters.
`item_types`	`list[ItemCollectionItemType] \| null`	No	The item type definitions, such as a `product` type with a `variant` relationship. Defaults to an empty list.

Response parameters

The tool returns an ItemCollectionResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`ItemCollectionSummary \| null`	The created item collection's details.
`error`	`str \| null`	Error message if the operation failed.

The ItemCollectionSummary object has the following fields:

Field	Type	Description
`id`	`str`	The collection's unique ID.
`name`	`str`	The machine-readable collection name.
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	The collection description.
`workspace_id`	`str`	The workspace this collection belongs to.
`item_types`	`list[ItemCollectionItemType]`	The item type definitions and their relationship types.
`created`	`float \| null`	Unix timestamp of when the collection was created.
`edited`	`float \| null`	Unix timestamp of when the collection was last edited.

update_item_collection_metadata

Updates the metadata on an existing item collection. You can change the display name, the description, or the item type definitions. This tool doesn't touch the schema or the destinations, which belong to update_item_collection_configuration.

Only the fields you provide reach the backend, so omitted fields keep their current values. At least one of display_name, description, or item_types is required. Note that item_types replaces the whole list rather than merging into it, so send every type you want to keep. Confirm the exact collection_name with the user before calling, and use search_item_collections to list the options if you need to. The tool records a before-state snapshot for auditing, calls are idempotent, and writes are 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.
`display_name`	`str \| null`	No	The updated human-readable display name, 1 to 128 characters.
`description`	`str \| null`	No	The updated collection description, up to 1,024 characters.
`item_types`	`list[ItemCollectionItemType] \| null`	No	The updated item type definitions. Replaces the full `item_types` list.

Response parameters

The tool returns an ItemCollectionResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`ItemCollectionSummary \| null`	The updated item collection's details.
`error`	`str \| null`	Error message if the operation failed.

The ItemCollectionSummary object has the following fields:

Field	Type	Description
`id`	`str`	The collection's unique ID.
`name`	`str`	The machine-readable collection name.
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	The collection description.
`workspace_id`	`str`	The workspace this collection belongs to.
`item_types`	`list[ItemCollectionItemType]`	The item type definitions and their relationship types.
`created`	`float \| null`	Unix timestamp of when the collection was created.
`edited`	`float \| null`	Unix timestamp of when the collection was last edited.

delete_item_collection

Permanently deletes a Data hub item collection. This is irreversible, with no undo. The call enqueues a background job that removes the collection's records, items, and indexes, so cleanup finishes asynchronously rather than at the moment the tool returns.

Deletion is blocked when the collection configuration still has destinations attached. Remove them with update_item_collection_configuration first, then delete. Get explicit confirmation of the exact collection_name from the user before you call, since deleting the wrong collection breaks whichever catalogs and recommendations depend on it. Verify the target with search_item_collections, and check the linkage with search_datahub_catalogs if you need to know which catalogs a collection backs. The tool records a before-state snapshot for auditing. Deletes aren't idempotent, so a second call fails, and they're throttled to one call every 10 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 delete. Get explicit confirmation of the exact name before calling. Use `search_item_collections` to list the options.

Response parameters

The tool returns an ItemCollectionDeleteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the delete succeeded.
`error`	`str \| null`	Error message if the delete failed.