Product catalogs and recommendations tools

search_catalogs: List the catalogs in a project, or fetch one by ID.
search_catalog_items: Search items inside a catalog.
get_catalog_item: Get a single item from a catalog by its item ID.
get_catalog_configuration: Get the attribute schema for a catalog.
list_catalog_jobs: List the import and update jobs for a catalog.
get_catalog_usages: See which campaigns and engines reference a catalog.
upsert_catalog_item: Create or replace a single item in a catalog.
delete_catalog_item: Permanently delete a single item from a catalog.
import_catalog_items: Apply a batch of item changes to a v2 catalog in one call.
search_recommendations: List the recommendation engines in a project, or fetch one by ID.
get_customer_recommendations: Run a recommendation engine for a specific customer and return the ranked products.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Marketing dashboard, actions your users or agents take with these tools can have a substantial impact on your catalogs and on the recommendations and campaigns that depend on them. There is no automatic rollback, so review every change and confirm the target before applying it.

search_catalogs

Searches the catalogs in a project, or fetches one by ID. Catalogs store product or generic data that's used for recommendations and personalization.

Omit catalog_id to list all catalogs — you get summary records: name, display name, type (generic, product, or variant), and metadata. Pass catalog_id to fetch the full definition of a single catalog, including every field's name and data type.

Item writes go through upsert_catalog_item, delete_catalog_item, and import_catalog_items (v2 only), which redirect you to the Data hub tools when search_datahub_catalogs shows the catalog is managed by an item collection.

Projects can be on either of two catalog generations, v1 or v2, and this tool covers both. Every record carries a catalog_version of v1 or v2, which tells you which generation you're looking at and which sibling tools will work against it.

List mode queries the v1 and v2 endpoints at the same time and concatenates the results. A catalog belongs to exactly one generation, so the two sets never overlap and nothing is deduplicated. Detail mode needs no such handling, because fetching one catalog by ID works the same way for both generations.

🚧
Warning
Two response patterns are worth knowing:

If one generation's endpoint fails while the other answers, success is false and error names the side that failed, for example v1 catalogs: HTTP 500. data still holds every catalog the working side returned, so the results are usable even though the call is marked unsuccessful.

If some records fail validation, success stays true and error reports how many were skipped.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str \| null`	No	The catalog ID for direct lookup. Omit to list all; provide to fetch one.

Response parameters

The tool returns a CatalogsResponse when catalog_id is omitted, or a CatalogResponse when it's provided.

The CatalogsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogSummary]`	The catalog summaries.
`error`	`str \| null`	Error message if the request failed.

The CatalogSummary object has the following fields:

Field	Type	Description
`id`	`str`	The catalog's unique ID.
`name`	`str`	The machine-readable catalog name (lowercase with underscores).
`display_name`	`str \| null`	The human-readable display name.
`description`	`str \| null`	A description of the catalog.
`type`	`str \| null`	The catalog type: `generic`, `product`, or `variant`.
`catalog_version`	`str \| null`	The catalog generation, `v1` or `v2`. A `null` value implies v2-era data.
`created`	`any \| null`	Unix timestamp of when the catalog was created.
`created_by_display_name`	`str \| null`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str \| null`	Display name of the last editor.

The CatalogResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Catalog \| null`	The full catalog definition.
`error`	`str \| null`	Error message if the request failed.

The Catalog object adds the following field on top of the summary record:

Field	Type	Description
`fields`	`list[CatalogFieldDef]`	The field definitions for this catalog. Each entry has a `name`, a `type` (`string`, `number`, `boolean`, `date`, and so on), and a `searchable` flag.

search_catalog_items

Searches and lists items inside a catalog. Items are the records used for recommendations and search. Each item is returned as a flat dictionary of field values keyed by field name. You can search across all fields or restrict the search to a specific field.

The tool works against both catalog generations. It resolves the catalog's catalog_version once, then queries the matching endpoint, so you don't need to know or pass the generation yourself. The response contract is identical either way: v1 records store the item ID under item_id, and the tool renames it to _id to match v2. If the catalog ID doesn't resolve to a catalog at all, success is false and error reads Catalog '<id>' not found.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`.
`query`	`str`	No	Search text. Defaults to an empty string. When `field` is not set, the search runs across all fields.
`field`	`str \| null`	No	A specific field name to search within. Omit to search all fields.
`skip`	`int`	No	Pagination offset. Defaults to 0.
`count`	`int`	No	Number of items to return. Defaults to 20. Maximum 1,000.

Response parameters

The tool returns a CatalogItemsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[dict[str, any]]`	The catalog items, each as a flat dictionary keyed by field name.
`total`	`int`	The total number of items in the catalog.
`matched`	`int`	The number of items matching the search query.
`limit`	`int`	The maximum number of items returned.
`skip`	`int`	The pagination offset that was applied.
`error`	`str \| null`	Error message if the request failed.

get_catalog_item

Returns a single item from a catalog by its item ID. The item is returned as a flat dictionary of field values; the item ID is in the _id field. If no item matches, success is false and the response includes an error message.

Like search_catalog_items, this tool resolves the catalog's generation first and queries the v1 or v2 endpoint to match, normalizing a v1 record's item_id to _id so the shape is the same either way. There's no dedicated single-item endpoint behind it. The tool searches the items index on the item_id field and returns the first exact match.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`.
`item_id`	`str`	Yes	The item's ID, for example `A5` or `prod-12345`.

Response parameters

The tool returns a CatalogItemResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`dict[str, any] \| null`	The catalog item fields as a flat dictionary. The item ID is in the `_id` field.
`error`	`str \| null`	Error message if the request failed or the item was not found.

get_catalog_configuration

Returns the attribute schema for a catalog: custom attributes the user has defined (with name, type, and the catalog column they map to) and reserved system attributes (such as product_id, title, and price). Also returns a configuration_hash you can use to detect schema drift between snapshots.

Catalog configuration is a v2-only concept. Against a v1 catalog, success is false and error reads Catalog configuration is not available for v1 catalogs. That's a deliberate message rather than the bare 404 the v2 endpoint would otherwise return for a v1 ID, which gave no clue whether the catalog was missing or simply on the older generation. Check catalog_version on the record from search_catalogs if you're unsure which generation a catalog is on.

Separately, the tool returns a 404 if a v2 catalog has no configuration yet, for example because no configuration-update job has run.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`.

Response parameters

The tool returns a CatalogConfigurationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogConfigurationData \| null`	The catalog's attribute schema.
`error`	`str \| null`	Error message if the request failed.

The CatalogConfigurationData object has the following fields:

Field	Type	Description
`catalog_id`	`str`	The catalog's ID.
`project_id`	`str`	The project ID.
`configuration_hash`	`str`	A SHA256 hash of the configuration. Useful for detecting schema drift between versions.
`custom_attribute_definitions`	`list[CatalogAttributeDefinition]`	User-defined attribute definitions, sorted alphabetically by name.
`reserved_attribute_mappings`	`list[CatalogAttributeDefinition]`	System reserved attribute mappings (such as `product_id`, `title`, `price`, and `brand`), sorted in their standard order.

The CatalogAttributeDefinition object has the following fields:

Field	Type	Description
`name`	`str`	The attribute's name.
`record_field_name`	`str`	The catalog record field this attribute maps to.
`searchable`	`bool \| null`	Whether the attribute is included in full-text search.
`attribute_value_definition`	`CatalogAttributeValueDefinition`	Type information for the attribute.

The CatalogAttributeValueDefinition object has the following fields:

Field	Type	Description
`type`	`str`	One of `String`, `Integer`, `Float`, `Boolean`, `Date`, `Datetime`, `List.String`, `List.Integer`, or `List.Float`.

list_catalog_jobs

Lists the job history for a catalog. Jobs represent data ingestion and update operations: imports, parses, items-updates, configuration-updates, and so on. Use it to check data freshness or diagnose upload failures.

It covers both standard catalogs, which draw their history from the job database, and item-collection-managed catalogs, which draw from the job reporting service.

After a write with upsert_catalog_item, delete_catalog_item, or import_catalog_items against a v2 catalog, poll the returned items_update_job_id here — its job type is items-update — before you treat search_catalog_items results as current.

Catalog jobs are a v2-only concept. Against a v1 catalog, success is false and error reads Catalog jobs are not available for v1 catalogs, instead of the unexplained 404 a v1 ID used to produce. Check catalog_version on the record from search_catalogs when you need to know which generation you're on.

Job statistics pass through an internal map that keeps the user-facing metrics and drops low-level internal counters.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`.
`skip`	`int`	No	Pagination offset. Defaults to 0.
`count`	`int`	No	Number of jobs to return. Defaults to 20. Maximum 1,000.

Response parameters

The tool returns a CatalogJobsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogJob]`	The catalog jobs, most recent first.
`total`	`int`	The total number of jobs for this catalog.
`matched`	`int`	The number of jobs matching the query.
`matched_limited`	`bool`	Whether the match count was capped by a server limit.
`limit`	`int`	The maximum number of jobs returned.
`skip`	`int`	The pagination offset that was applied.
`error`	`str \| null`	Error message if the request failed.

The CatalogJob object has the following fields:

Field	Type	Description
`id`	`str`	The job's unique ID.
`catalog_id`	`str`	The catalog ID.
`project_id`	`str`	The project ID.
`type`	`str`	The job type: `import`, `parse`, `download`, `items-update`, `configuration-update`, or `delete-catalog`.
`state`	`str`	The job state: `pending`, `running`, `success`, `fail`, or `canceled`.
`status_code`	`int`	The status code: 102 (processing), 200 (success), 210 (success with warnings), 305 (no-op), 310 (skipped), 400 (bad definition), 440 (pre-condition failure), 450 (post-condition failure), 500 (error), or 550 (fatal).
`stats`	`dict[str, any]`	Job statistics such as `records_total`, `items_total`, `records_added_total`, `records_deleted_total`, `items_updated_total`, `items_deleted_total`, `feed_total_ops`, and `feed_total_bytes`.
`properties`	`dict[str, any]`	Job properties. The shape varies by job type.
`logs`	`list[any]`	Job log entries.
`details`	`list[any]`	Job detail messages.
`created`	`str \| null`	ISO 8601 timestamp of when the job was created.
`created_by_id`	`str`	The user ID of the person who created the job.
`created_by_display_name`	`str`	Display name of the job's creator.
`edited`	`str \| null`	ISO 8601 timestamp of the last edit.
`started`	`str \| null`	ISO 8601 timestamp of when the job started running.
`requested_cancel`	`str \| null`	ISO 8601 timestamp of when cancellation was requested.
`runnable`	`str \| null`	ISO 8601 timestamp of when the job became runnable.

get_catalog_usages

Returns the cross-references for a catalog: which scenarios, recommendation engines, email campaigns, SMS campaigns, banners, experiments, in-app messages, and surveys reference it, plus whether the catalog is used in the project's custom data mapping. Check this before you delete or restructure a catalog.

This works for both catalog generations. The tool resolves the catalog's catalog_version first, then queries the matching endpoint. System scenarios that sit behind email campaigns are stripped from the scenarios list to cut noise, so those campaigns appear under email_campaigns instead.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`.

Response parameters

The tool returns a CatalogUsagesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`used_by`	`CatalogUsedBy`	Cross-references grouped by resource type.
`used_by_data_mapping`	`bool`	Whether the catalog is referenced in the project's custom data mapping.
`error`	`str \| null`	Error message if the request failed.

The CatalogUsedBy object has the following fields:

Field	Type	Description
`scenarios`	`list[CatalogUsageEntry]`	Scenarios using this catalog.
`recommendations`	`list[CatalogUsageEntry]`	Recommendation engines using this catalog.
`email_campaigns`	`list[CatalogUsageEntry]`	Email campaigns using this catalog.
`sms_campaigns`	`list[CatalogUsageEntry]`	SMS campaigns using this catalog.
`banners`	`list[CatalogUsageEntry]`	Weblayer banners using this catalog.
`experiments`	`list[CatalogUsageEntry]`	A/B experiments using this catalog.
`in_app_messages`	`list[CatalogUsageEntry]`	In-app messages using this catalog.
`surveys`	`list[CatalogUsageEntry]`	Surveys using this catalog.
`other`	`list[CatalogUsageEntry]`	Other resources using this catalog.

The CatalogUsageEntry object has the following fields:

Field	Type	Description
`id`	`str`	The resource's ID.
`name`	`str`	The resource's display name.

upsert_catalog_item

Creates or replaces a single item in a catalog. Use it to add one product record, or to correct the fields on an existing one, without running a full import. It works against both catalog versions: the tool resolves the catalog's catalog_version first, so you don't need to know or pass the version yourself.

The response depends on the catalog's version:

A v1 write is queued for background processing and returns queued with true, and no job ID. As a result, the searchable index can lag briefly behind the write.
A v2 write returns an items_update_job_id. Poll it with list_catalog_jobs before you treat search_catalog_items results as current.

If the catalog is backed by a Data hub item collection, the tool skips the write and returns success: false with guidance to use the Data hub item collection tools instead. Check item_collection_id on the record from search_datahub_catalogs to know whether that applies.

🚧
Warning
The write replaces the whole item. Any field you leave out of properties is not kept, so send the complete set of fields you want the item to end up with, not just the ones that changed. Property names must already exist on the catalog's schema, and an unknown name comes back as a validation error. Check the schema with get_catalog_configuration before you write.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`.
`item_id`	`str`	Yes	The item's identifier, for example a SKU or a product ID.
`properties`	`dict`	Yes	The item's fields, as a flat map of field name to value. This is a full replace, so fields you leave out are not kept.

Response parameters

The tool returns a CatalogWriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`items_update_job_id`	`str \| null`	The items-update job to poll with `list_catalog_jobs`. Returned for v2 catalogs only.
`configuration_update_job_id`	`str \| null`	The configuration-update job, on the rare occasion a write also changes catalog configuration. v2 catalogs only.
`queued`	`bool \| null`	Whether a v1 write was queued for background processing. Returned for v1 catalogs only.
`error`	`str \| null`	Error message if the operation failed.

delete_catalog_item

Permanently removes a single item from a catalog. Find item IDs with search_catalog_items or get_catalog_item.

Like upsert_catalog_item, this tool covers both catalog generations and resolves catalog_version for you. Deleting an item that's already gone counts as a success rather than an error, so a repeated delete is safe.

The response behaves the same way as it does for upsert:

A v1 delete is queued and returns queued with true.
A v2 delete returns an items_update_job_id. Poll it with list_catalog_jobs before you treat search_catalog_items results as current.

If the catalog is backed by a Data hub item collection, the tool skips the delete and returns success: false pointing you at the Data hub item collection tools.

🚧
Warning
This action is irreversible. There is no undo through this tool, so confirm the target before you run it.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`.
`item_id`	`str`	Yes	The item's identifier, for example a SKU or a product ID.

Response parameters

The tool returns a CatalogWriteResponse object, the same shape upsert_catalog_item returns:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`items_update_job_id`	`str \| null`	The items-update job to poll with `list_catalog_jobs`. Returned for v2 catalogs only.
`configuration_update_job_id`	`str \| null`	The configuration-update job, on the rare occasion a write also changes catalog configuration. v2 catalogs only.
`queued`	`bool \| null`	Whether a v1 delete was queued for background processing. Returned for v1 catalogs only.
`error`	`str \| null`	Error message if the operation failed.

import_catalog_items

Applies a batch of item changes to a catalog in one call. Each operation adds, upserts, or removes one item, so you can create, update, and delete several items together instead of writing them one at a time.

This tool supports v2 catalogs only. Check catalog_version on the record from search_catalogs, and use upsert_catalog_item and delete_catalog_item per item for a v1 catalog.

Operations follow a JSON Patch shape. Each entry has an op of add, upsert, or remove, a path that identifies the item as /{item_id}, and, for add and upsert, a value object holding the item's fields.

The call returns an items_update_job_id. Poll it with list_catalog_jobs before you treat search_catalog_items results as current. If the catalog is backed by a Data hub item collection, the tool skips the write and returns success: false pointing you at the Data hub item collection tools.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`catalog_id`	`str`	Yes	The catalog ID returned by `search_catalogs`. Must be a v2 catalog.
`operations`	`list`	Yes	The batch of changes. Each entry holds an `op` of `add`, `upsert`, or `remove`, a `path` of `/{item_id}`, and, for `add` and `upsert`, a `value` object of item fields.

Response parameters

The tool returns a CatalogWriteResponse object, the same shape upsert_catalog_item returns:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`items_update_job_id`	`str \| null`	The items-update job to poll with `list_catalog_jobs`.
`configuration_update_job_id`	`str \| null`	The configuration-update job, on the rare occasion a write also changes catalog configuration.
`queued`	`bool \| null`	Not set by this tool, which supports v2 catalogs only.
`error`	`str \| null`	Error message if the operation failed.

search_recommendations

Searches the recommendation engines in a project, or fetches one by ID. Recommendation engines power personalized product suggestions using collaborative filtering, neural models, or rule-based algorithms.

Omit recommendation_id to list all engines — you get summary records: name, status, tags, archived flag, and initiative assignment. Pass recommendation_id to fetch the full configuration of a single engine: algorithm type, the catalog it reads from, event mapping, filters, and output settings.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`recommendation_id`	`str \| null`	No	The recommendation engine ID for direct lookup. Omit to list all; provide to fetch one.

Response parameters

The tool returns a RecommendationsResponse when recommendation_id is omitted, or a RecommendationResponse when it's provided.

The RecommendationsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[RecommendationSummary]`	The recommendation engine summaries.
`error`	`str \| null`	Error message if the request failed.

The RecommendationSummary object has the following fields:

Field	Type	Description
`id`	`str`	The recommendation engine's unique ID.
`name`	`str`	The engine's display name.
`status`	`str`	One of `draft`, `active`, or `inactive`.
`archived`	`bool`	Whether the engine has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this engine belongs to, if any.
`created`	`any \| null`	Unix timestamp of when the engine was created.
`created_by_display_name`	`str \| null`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str \| null`	Display name of the last editor.

The RecommendationResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Recommendation \| null`	The full engine definition.
`error`	`str \| null`	Error message if the request failed.

The Recommendation object adds the following field on top of the summary record:

Field	Type	Description
`definition`	`any \| null`	The engine configuration: model type (collaborative filtering, neural, or rule-based), the catalog, event mapping, filters, and output settings.

get_customer_recommendations

Runs a recommendation engine for a single customer and returns the ranked list of products the engine suggests. Use it to check what an engine actually recommends for a named customer, for example to sanity-check results after a catalog update, or to compare two engines on the same customer.

This tool invokes the engine but doesn't change its definition, and it never tracks impression events, so the calls are diagnostic. Identify the engine with engine_id from search_recommendations, and identify the customer with customer_id plus its id_type. The customer_id is an external identifier, not the internal customer ID used by other customer tools.

🚧
Warning
This tool is in alpha, so its API or response shape may change.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`engine_id`	`str`	Yes	The recommendation engine ID to run, returned by `search_recommendations`.
`customer_id`	`str`	Yes	The customer's external identifier value, for example `user-1234` or `[email protected]`. This is an external ID, not the internal customer ID used by other tools.
`id_type`	`str`	No	The external identifier type that `customer_id` belongs to, as defined on the project, for example `registered`, `email`, or `cookie`. Defaults to `registered`.
`size`	`int`	No	The maximum number of items to return. Defaults to 10. Range 1–100.
`strategy`	`str`	No	Overrides the engine's strategy: `winner`, `mix`, or `priority`. Omit to use the engine's configured strategy.
`diversity_level`	`int`	No	The diversity tuning level from 1 (least diverse) to 5 (most diverse). Omit to use the engine default.
`use_case`	`str`	No	The recommendation use-case preset, for example `homepage`, `product_detail_page`, or `email_abandoned_cart`. Omit to use the engine default.

Response parameters

The tool returns a CustomerRecommendationsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[RecommendedItem]`	The ranked list of recommended catalog items for the customer.
`error`	`str \| null`	Error message if the request failed.

The RecommendedItem object has the following fields:

Field	Type	Description
`item_id`	`str`	The catalog item ID of the recommended product.
`product_id`	`str \| null`	The product ID. Defaults to `item_id` when it isn't present in the catalog properties.
`recommendation_id`	`str \| null`	The ID of the recommendation engine that produced this item.
`recommendation_variant_id`	`str \| null`	The A/B test variant ID, if the engine is under experiment.
`engine_name`	`str \| null`	The name of the model or sub-engine that selected this item, for example `cf`, `random`, `custom`, or `pinned`.
`recommendation_source`	`str \| null`	How the item was chosen: `model_personalized`, `model_non_personalized`, `model_fallback`, `fallback`, `pinned`, or `pinned_adjusted`.

Each item also passes through any additional catalog attributes, such as title, image, and price, flattened alongside the fields above.