Catalogs tools

list_discovery_catalogs: List the catalogs in your account, with their languages, environments, and statistics.
get_discovery_catalog: Get a single catalog's details by name.
get_discovery_catalog_config: Get a catalog's attribute configuration.
list_discovery_catalog_products: List the products in a catalog.
get_discovery_catalog_product: Get a single product's full attribute set by ID.
list_discovery_catalog_product_variants: List the variants for a product.
get_discovery_catalog_product_variant: Get a single variant's full attribute set by ID.
list_discovery_catalog_jobs: List the feed and index jobs for a catalog.
get_discovery_catalog_job: Get a single job's full details by ID.
get_discovery_catalog_reserved_attributes: Get the reserved attribute names for a catalog.

list_discovery_catalogs

Lists the catalogs in your account. A catalog holds the products and variants that power search and category pages. Each summary gives you the catalog name, language, environment (production or staging), and statistics such as document counts and index refresh timestamps.

The catalog name is required by most other catalog tools, so start here. Use get_discovery_catalog for a single catalog's details, and set account_name if you have access to more than one account.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.

Response parameters

The tool returns a DiscoveryCatalogsResponse object with the following parameters:

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

The CatalogSummary object has the following fields:

Field	Type	Description
`name`	`str`	The catalog name. Pass this to the other catalog tools.
`language`	`str \| null`	The catalog language code, for example `en`.
`environment`	`str \| null`	The environment: `production` or `staging`.
`stats`	`CatalogStats \| null`	Catalog statistics: document counts and index timestamps.
`properties`	`any \| null`	Catalog properties.
`data_hub_properties`	`any \| null`	Data hub integration properties.

The CatalogStats object has the following fields:

Field	Type	Description
`last_index_refresh_at`	`str \| null`	ISO timestamp of the last index refresh.
`last_keyword_suggest_refresh_at`	`str \| null`	ISO timestamp of the last keyword suggest refresh.
`product_doc_count`	`int \| null`	The number of product documents.
`product_doc_byte_count`	`int \| null`	The size of product documents, in bytes.
`variant_doc_byte_count`	`int \| null`	The size of variant documents, in bytes.
`catalog_searchable_byte_count`	`int \| null`	The size of searchable catalog data, in bytes.
`catalog_displayable_byte_count`	`int \| null`	The size of displayable catalog data, in bytes.
`catalog_facetable_manual_byte_count`	`int \| null`	The size of manually-facetable catalog data, in bytes.
`catalog_facetable_auto_byte_count`	`int \| null`	The size of auto-facetable catalog data, in bytes.

get_discovery_catalog

Returns the details of a single catalog by name, including its statistics, properties, and Data hub properties for the chosen environment.

Use list_discovery_catalogs to find catalog names.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `list_discovery_catalogs`.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.

Response parameters

The tool returns a DiscoveryCatalogResponse object with the following parameters:

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

The CatalogSummary object is described under list_discovery_catalogs.

get_discovery_catalog_config

Returns the latest attribute configuration for a catalog. The configuration defines which attributes are searchable, displayable, facetable (manual and auto), and sortable. Use it to understand what attributes a catalog exposes and how they're set up for search and merchandising.

The configuration is a large freeform JSON object. Use list_discovery_catalogs to find catalog names.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name, for example `ucg_automation_com`.
`environment`	`str`	No	The environment: `production` or `staging`. Defaults to `production`.

Response parameters

The tool returns a DiscoveryCatalogConfigResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The catalog configuration, as freeform JSON: searchable, displayable, facetable, and sortable attribute definitions.
`error`	`str \| null`	Error message if the request failed.

list_discovery_catalog_products

Lists the products in a catalog. Each record includes the product ID, its attribute key-value pairs, and a variant count. Pages are 1-based, so the first page is 1.

Use get_discovery_catalog_product for a single product, and list_discovery_catalog_product_variants to list a product's variants.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `list_discovery_catalogs`.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.
`page`	`int`	No	Page number, 1-based. Defaults to `1`.
`limit`	`int`	No	Results per page. Defaults to `10`.

Response parameters

The tool returns a DiscoveryCatalogProductsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogProduct]`	The products in the catalog.
`count`	`int \| null`	The total number of products.
`error`	`str \| null`	Error message if the request failed.

The CatalogProduct object has the following fields:

Field	Type	Description
`id`	`str`	The product ID.
`attributes`	`dict \| null`	The product's attribute key-value pairs.
`variant_record_count`	`int \| null`	The number of variants for this product.

get_discovery_catalog_product

Returns a single product's full attribute set and variant count by ID.

Use list_discovery_catalog_products to find product IDs.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `list_discovery_catalogs`.
`product_id`	`str`	Yes	The product ID returned by `list_discovery_catalog_products`.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.

Response parameters

The tool returns a DiscoveryCatalogProductResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogProduct \| null`	The product details.
`error`	`str \| null`	Error message if the request failed.

The CatalogProduct object is described under list_discovery_catalog_products.

list_discovery_catalog_product_variants

Lists the variants for a product in a catalog. Each record includes the variant ID and its attribute key-value pairs. Pages are 1-based, so the first page is 1.

Use list_discovery_catalog_products to find product IDs, and get_discovery_catalog_product_variant for a single variant.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `list_discovery_catalogs`.
`product_id`	`str`	Yes	The product ID returned by `list_discovery_catalog_products`.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.
`page`	`int`	No	Page number, 1-based. Defaults to `1`.
`limit`	`int`	No	Results per page. Defaults to `10`.

Response parameters

The tool returns a DiscoveryCatalogVariantsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogVariant]`	The variants for the product.
`count`	`int \| null`	The total number of variants.
`error`	`str \| null`	Error message if the request failed.

The CatalogVariant object has the following fields:

Field	Type	Description
`id`	`str`	The variant ID.
`attributes`	`dict \| null`	The variant's attribute key-value pairs.

get_discovery_catalog_product_variant

Returns a single variant's full attribute set by ID.

Use list_discovery_catalog_product_variants to find variant IDs.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `list_discovery_catalogs`.
`product_id`	`str`	Yes	The product ID returned by `list_discovery_catalog_products`.
`variant_id`	`str`	Yes	The variant ID returned by `list_discovery_catalog_product_variants`.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.

Response parameters

The tool returns a DiscoveryCatalogVariantResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogVariant \| null`	The variant details.
`error`	`str \| null`	Error message if the request failed.

The CatalogVariant object is described under list_discovery_catalog_product_variants.

list_discovery_catalog_jobs

Lists the feed and index jobs for a catalog. Jobs process catalog feeds and rebuild the search index. Each record includes the job status, type, timestamps, and document-count statistics. Filter by status, visibility, or a creation-date range. Pages are 1-based, so the first page is 1.

To find jobs that failed, set status to failure. Use get_discovery_catalog_job for a single job's full details.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `list_discovery_catalogs`.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.
`page`	`int`	No	Page number, 1-based. Defaults to `1`.
`limit`	`int`	No	Results per page. Defaults to `50`.
`status`	`str \| null`	No	Status filter: `running`, `queued`, `success`, `failure`, `failed`, `killed`, or `skipped`.
`visibility`	`str \| null`	No	Visibility filter: `external`, `internal`, or `all`.
`created_at_min`	`str \| null`	No	ISO 8601 timestamp lower bound for the job creation date.
`created_at_max`	`str \| null`	No	ISO 8601 timestamp upper bound for the job creation date.

Response parameters

The tool returns a DiscoveryCatalogJobsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CatalogJob]`	The feed and index jobs for the catalog.
`count`	`int \| null`	The total number of jobs.
`error`	`str \| null`	Error message if the request failed.

The CatalogJob object has the following fields:

Field	Type	Description
`id`	`str`	The job ID.
`type`	`str \| null`	The job type: `feed`, `index`, or `suggest`.
`status`	`str \| null`	The job status: `running`, `queued`, `success`, `failure`, `failed`, `killed`, or `skipped`.
`status_message`	`str \| null`	A human-readable status message.
`created_at`	`str \| null`	ISO timestamp of when the job was created.
`started_at`	`str \| null`	ISO timestamp of when the job started.
`stopped_at`	`str \| null`	ISO timestamp of when the job stopped.
`visibility`	`str \| null`	The job visibility: `external`, `internal`, or `all`.
`properties`	`JobProperties \| null`	Job properties: feed type, mode, and input source.
`stats`	`JobStats \| null`	Job statistics: document counts.

The JobProperties object has the following fields:

Field	Type	Description
`feed_data_type`	`str \| null`	The feed data type: `products`, `ae`, `qd`, `ltr`, or `product_vectors`.
`feed_mode`	`str \| null`	The feed mode: `full` or `delta`.
`input_source`	`str \| null`	The input source: `sftp_file_upload` or `api_request_body`.
`input_filenames`	`list[str] \| null`	The input file names.
`config_etag`	`str \| null`	The config ETag at the time the job ran.
`index_mode`	`str \| null`	The index mode: `update`, `refresh`, or `export`.
`ignore_count_drop`	`bool \| null`	Whether count-drop protection was bypassed.

The JobStats object has the following fields:

Field	Type	Description
`patch_operation_count`	`int \| null`	The number of patch operations.
`product_doc_count`	`int \| null`	The number of product documents processed.
`variant_doc_count`	`int \| null`	The number of variant documents processed.
`search_variant_count`	`int \| null`	The number of search variant documents.
`search_product_count`	`int \| null`	The number of search product documents.
`deleted_parent_count`	`int \| null`	The number of deleted parent documents.

get_discovery_catalog_job

Returns the full details of a single job by ID, including its status, timestamps, properties, and statistics.

Use list_discovery_catalog_jobs to find job IDs.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name returned by `list_discovery_catalogs`.
`job_id`	`str`	Yes	The job ID returned by `list_discovery_catalog_jobs`.
`account_name`	`str \| null`	No	The account name. If you have exactly one account, it's selected automatically. Use `list_discovery_accounts` to see available accounts.
`environment`	`str`	No	The environment: `production` or `staging`.

Response parameters

The tool returns a DiscoveryCatalogJobResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`CatalogJob \| null`	The job details.
`error`	`str \| null`	Error message if the request failed.

The CatalogJob object is described under list_discovery_catalog_jobs.

get_discovery_catalog_reserved_attributes

Returns the reserved attribute names for a catalog. Reserved attributes are system-defined names that you can't use as custom attribute names in a catalog feed. Using a reserved name as a custom attribute causes feed ingestion errors.

Check this list before you add new attributes to your feed to avoid naming conflicts. Use list_discovery_catalogs to find catalog names.

Request parameters

Name	Type	Required?	Description
`catalog_name`	`str`	Yes	The catalog name, for example `ucg_automation_com`.
`environment`	`str`	No	The environment: `production` or `staging`. Defaults to `production`.

Response parameters

The tool returns a DiscoveryReservedAttributesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The reserved attribute names, as freeform JSON.
`error`	`str \| null`	Error message if the request failed.