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

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.

Projects can be on either of two catalog generations, v1 or v2, and this tool covers both. 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. 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. Detail mode needs no such handling, because fetching one catalog by ID works the same way for both generations.

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 — but data still holds every catalog the working side returned, so the results are usable even though the call is marked unsuccessful. Separately, 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 Elasticsearch-backed 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. Useful for checking data freshness or diagnosing 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.

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.

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.

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.