Item collections tools

search_item_collections: List the item collections in a workspace, or fetch one by name.
search_item_types: List the item types defined in a collection, 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.
create_item_type: Add a new item type to an existing item collection.
update_item_collection_metadata: Update a collection's display name or description.
update_item_type: Update an item type's display name or description.
delete_item_type: Permanently delete an item type and enqueue cleanup of its data.
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.

A collection reports its item types in two shapes: the newer types field and the older item_types field. Both are always populated on the response, so read whichever one your integration already expects. To manage individual types, use the dedicated search_item_types, create_item_type, update_item_type, and delete_item_type tools.

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, in the older shape. Derived from `types` when the collection only reports that one.
`types`	`list[ItemCollectionType]`	The item types, with their `item_class` and per-type destinations. Derived from `item_types` when the collection only reports that one.
`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`.

The ItemCollectionType object has the following fields:

Field	Type	Description
`name`	`str`	The item type name, such as `product` or `store`.
`item_class`	`str`	The item class: `product` or `custom`.
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	The item type description.
`relationships`	`list[str]`	The relationship types this item type supports, such as `variant`.
`destinations`	`dict \| null`	Destinations configured for this type, grouped as `{engagement: [...], discovery: [...]}`. A `null` value means this entry was derived from the older shape.

search_item_types

Lists the item types defined in a Data hub item collection, or fetches one by name. A collection can hold several item types, and each one carries its own schema, fields, records, and items.

Every item type has a name, a display_name, a description, its relationships, and an item_class of either:

product, which may define variant relationships.
custom, a flat item type with no relationships.

Omit item_type to list every type in the collection, or pass it to fetch one. search_item_collections already returns a collection's types, so reach for this tool when you want a single type, or the freshest view right before you create, update, or delete one.

This tool performs no writes, and its results reflect live data, so they may vary between calls.

📘
Note
On a Data hub deployment that doesn't yet have custom item types enabled, only the product type is visible. Malformed entries are skipped and counted rather than failing the whole call.

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_type`	`str \| null`	No	An item type name for a direct lookup, such as `store`. Omit to list all item types in the collection.

Response parameters

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

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

When you pass item_type, the tool returns an ItemTypeResponse object with the following parameters:

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

The ItemType object has the following fields:

Field	Type	Description
`collection_id`	`str`	The collection's unique ID.
`collection_name`	`str`	The machine-readable collection name.
`workspace_id`	`str`	The workspace this item type belongs to.
`name`	`str`	The item type name, such as `product` or `store`.
`item_class`	`str`	The item class: `product` or `custom`.
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	The item type description.
`relationships`	`list[str]`	The relationship types this item type supports, such as `variant`.
`created`	`float \| null`	Unix timestamp of when the type was created, taken from the parent collection.
`edited`	`float \| null`	Unix timestamp of the last edit, taken from the parent collection.
`created_by`	`str \| null`	The display name of the creator.
`created_by_id`	`str \| null`	The ID of the user or service that created the item type.
`edited_by`	`str \| null`	The display name of the last editor.
`edited_by_id`	`str \| null`	The ID of the user or service that last edited the item type.

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.

🚧
Warning
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.

Pagination uses the base64-encoded cursor in meta.next_page_token rather than a page number.

🚧
Warning
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.

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.

Resolve the organization and workspace with list_cloud_organizations and list_workspaces first.

🚧
Warning
Creation isn't idempotent, so a second call with the same name fails. A blank workspace_id is rejected before any call is made. Write tools are throttled to one call every five seconds and 10 per minute.

There are two ways to define item types at creation time, and you pick one. Prefer types, the newer shape, which carries an item_class per type. The older item_types shape is still accepted.

🚧
Warning
Sending both types and item_types in the same call is rejected before any request is made, as is a custom type that sets relationships. On a Data hub deployment that doesn't yet have custom item types enabled, only the product name and class are accepted.

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.
`types`	`list[ItemTypeInput] \| null`	No	The item type definitions, such as `[{name: 'product', item_class: 'product', relationships: ['variant']}, {name: 'store', item_class: 'custom'}]`. Not combinable with `item_types`.
`item_types`	`list[ItemCollectionItemType] \| null`	No	The older item type definitions, such as `[{type: 'product', relationships: ['variant']}]`. Prefer `types`. When you omit both, the collection is created with no item types.

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.

create_item_type

Adds a new item type to an existing Data hub item collection. Use it when a collection needs to hold something beyond its products, such as a store or a review type, each with its own schema and its own records.

The name must match ^[A-Za-z][A-Za-z0-9_]{0,15}$, so it starts with a letter and continues with letters, digits, or underscores. Confirm both the exact collection_name and the new type's name with the user before you call, rather than inventing a name. Creating a name that already exists in the collection fails.

The item_class decides what the type can do:

A product class may define variant relationships.
A custom class holds flat items and can't have relationships at all.

Storage for the new type initializes immediately, so there's no separate job to wait on.

📘
Note
On a Data hub deployment that doesn't yet have custom item types enabled, only product is accepted.

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 name of the collection to add the type to. Confirm the exact name with the user. Use `search_item_collections` to list the options.
`name`	`str`	Yes	The item type name, such as `store`. Must match `^[A-Za-z][A-Za-z0-9_]{0,15}$`. Ask the user for this value rather than inventing one.
`item_class`	`str`	No	The item class: `product` or `custom`. Defaults to `product`.
`display_name`	`str \| null`	No	The human-readable display name, 1 to 128 characters. Defaults to `name` when omitted.
`description`	`str \| null`	No	The item type description, up to 1,024 characters.
`relationships`	`list[str] \| null`	No	The relationship types this item type supports, such as `["variant"]`. Valid only when `item_class` is `product`.

Response parameters

The tool returns an ItemTypeResponse object with the following parameters:

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

The ItemType object has the following fields:

Field	Type	Description
`collection_id`	`str`	The collection's unique ID.
`collection_name`	`str`	The machine-readable collection name.
`workspace_id`	`str`	The workspace this item type belongs to.
`name`	`str`	The item type name, such as `product` or `store`.
`item_class`	`str`	The item class: `product` or `custom`.
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	The item type description.
`relationships`	`list[str]`	The relationship types this item type supports, such as `variant`.
`created`	`float \| null`	Unix timestamp of when the type was created, taken from the parent collection.
`edited`	`float \| null`	Unix timestamp of the last edit, taken from the parent collection.
`created_by`	`str \| null`	The display name of the creator.
`created_by_id`	`str \| null`	The ID of the user or service that created the item type.
`edited_by`	`str \| null`	The display name of the last editor.
`edited_by_id`	`str \| null`	The ID of the user or service that last edited the item type.

update_item_collection_metadata

Updates the metadata on an existing item collection. You can change the display name or the description. 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 or description must be provided. 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.

📘
Note
Item types are no longer managed here. To add or remove one on an existing collection, use create_item_type or delete_item_type instead.

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.

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.

update_item_type

Updates the metadata on an item type. You can change its display_name or its description. The name, the item_class, and the relationships are fixed at creation, so to change any of those, delete the type with delete_item_type and create it again.

Only the fields you provide reach the backend, so omitted fields keep their current values. At least one of display_name or description is required. Confirm the exact collection_name and item_type with the user before calling, and use search_item_types 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`	Yes	The name of the collection that holds the type. Confirm the exact name with the user. Use `search_item_collections` to list the options.
`item_type`	`str`	Yes	The name of the item type to update. Confirm the exact name with the user. Use `search_item_types` 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 item type description, up to 1,024 characters.

Response parameters

The tool returns an ItemTypeResponse object with the following parameters:

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

The ItemType object has the same fields the create_item_type response returns.

delete_item_type

Permanently removes an item type from a Data hub item collection. The call deletes the type's configuration along with any Marketing destination catalogs attached to it, then queues a background cleanup of its records, items, and indexes.

🚧
Warning
This is irreversible, and can't be undone. Get explicit confirmation of the exact item_type from the user before you call, and use search_item_types to list the options.

Deletion is blocked while a catalog of this type is still referenced by a live campaign or scenario. The error names what's using it, so you can resolve those references first and then retry.

On Data hub deployments with custom item types enabled, every item type has to be removed with this tool before the collection itself can be deleted with delete_item_collection. The tool records a before-state snapshot for auditing.

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 name of the collection that holds the type. Confirm the exact name with the user. Use `search_item_collections` to list the options.
`item_type`	`str`	Yes	The name of the item type to delete. Get explicit confirmation of the exact name before calling. Use `search_item_types` to list the options.

Response parameters

The tool returns an ItemTypeDeleteResponse object with the following parameters:

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

delete_item_collection

Permanently deletes a Data hub item collection. The call enqueues a background job that removes the collection's records, items, and indexes, so cleanup finishes asynchronously rather than when the tool returns.

🚧
Warning
This is irreversible, and can't be undone. 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.

Two conditions block deletion, depending on the deployment:

On a Data hub deployment with custom item types enabled, deletion is blocked while the collection still has item types. The error names them, and you remove each one with delete_item_type, confirming the exact name with the user every time, before you retry.
On a deployment without custom item types, deletion is instead blocked while the collection configuration still has destinations attached, so remove them with update_item_collection_configuration first.

In either case, this tool never cascades, so nothing is removed on your behalf.

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.