Facet rules tools

list_site_search_facets: List the site-search facet rules for an account.
list_facets_global: List the global facet rules that apply across site search and category pages.
list_category_facets: List the category facet rules for an account.
list_facet_attributes: List the product attributes available for facet configuration.
get_facet_rule: Get the full configuration of a single facet rule.
create_facet_rule: Create a new facet rule that controls which filters appear.
update_facet_rule: Update an existing facet rule.
delete_facet_rule: Permanently delete a facet rule.

🚧
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 live search and category experience. There is no automatic rollback and activity logging is limited, so review every change and confirm the target before applying it.

list_site_search_facets

Lists the site-search facet rules for an account. Facets are the filter options shown alongside search results, such as Brand, Color, Price range, or Size. A facet rule controls which facets appear, their order, and how they behave, for example multi-select versus single-select. This tool returns every site-search facet rule in one response, without pagination.

Use get_facet_rule for a rule's full configuration. For global facets that apply across both site search and category pages, use list_facets_global. For category-specific facets, use list_category_facets.

Request parameters

Name	Type	Required?	Description
`merchant_key`	`str`	Yes	The merchant key identifying the account, for example `your-account`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

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

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, `facet`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`queries`	`list[CustomizationQuery]`	The queries this facet rule applies to.
`groupBy`	`str \| null`	The group-by attribute, for example `color`.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_facets_global

Lists the global facet rules for an account. Global facet rules apply across both site-search and category pages, so shoppers see a consistent set of filter options however they navigate the catalog. This tool returns every global facet rule in one response, without pagination.

Use get_facet_rule for a rule's full configuration. For site-search facets, use list_site_search_facets. For category facets, use list_category_facets.

Request parameters

Name	Type	Required?	Description
`merchant_key`	`str`	Yes	The merchant key identifying the account, for example `your-account`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

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

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, `facet`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`queries`	`list[CustomizationQuery]`	The queries this facet rule applies to.
`groupBy`	`str \| null`	The group-by attribute, for example `color`.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_category_facets

Lists the category facet rules for an account. Category facet rules control which facets appear on category pages and how they behave. Unlike global facets that apply everywhere, category facets are specific to browsing. For example, a Size facet can appear only on clothing categories, or a Resolution facet only on electronics. This tool returns every category facet rule in one response, without pagination.

Use get_facet_rule for a rule's full configuration. For site-search facets, use list_site_search_facets. For global facets, use list_facets_global.

Request parameters

Name	Type	Required?	Description
`merchant_key`	`str`	Yes	The merchant key identifying the account, for example `your-account`.

Response parameters

The tool returns a CustomizationsResponse object with the following parameters:

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

The CustomizationSummary object has the following fields:

Field	Type	Description
`id`	`int`	The unique customization ID.
`name`	`str \| null`	The rule's display name.
`ruleType`	`str`	The rule type, `facet`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`queries`	`list[CustomizationQuery]`	The queries this facet rule applies to.
`groupBy`	`str \| null`	The group-by attribute, for example `color`.

The CustomizationQuery object has the following fields:

Field	Type	Description
`id`	`int \| null`	The query identifier.
`query`	`str \| null`	The query text, for example `green shoes`.
`type`	`str \| null`	The query type, for example `sitesearch` or `category`.

list_facet_attributes

Lists the product attributes available for facet configuration. Each result gives an attribute field name, such as brand, color, or Rating, that you can use when you define which facets a rule boosts, buries, excludes, or always includes. Take the name field from each result as the attribute identifier.

By default the response returns only facetable attributes. Set only_facetable to false to see every attribute. The results are paginated, so use page and limit for large catalogs, and query to search by attribute name.

Request parameters

Name	Type	Required?	Description
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Omit for account level.
`query`	`str \| null`	No	Text search to filter attributes by name, for example `brand` or `color`.
`only_facetable`	`bool`	No	When true (default), returns only attributes usable as facet filters. Set to false to see all attributes.
`page`	`int`	No	The page number, 0-based. Defaults to `0`.
`limit`	`int`	No	Results per page. Defaults to `50`, maximum `200`.
`sort_by`	`str`	No	Sort field: `NAME` (default), `ID`, `TYPE`, or `FACETABLE`.
`sort_order`	`str`	No	Sort direction: `ASC` (default) or `DESC`.

Response parameters

The tool returns a FacetAttributesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[FacetAttribute]`	The facet attributes.
`error`	`str \| null`	Error message if the request failed.
`total`	`int \| null`	The total number of matching attributes across all pages.
`page`	`int \| null`	The current page number, 0-based.
`total_pages`	`int \| null`	The total number of pages.

The FacetAttribute object has the following fields:

Field	Type	Description
`id`	`int \| null`	The internal attribute ID.
`name`	`str`	The attribute field name. Use this value when you configure facets in a rule.
`type`	`str \| null`	The attribute type: `STR` (text), `NUM` (numeric), or `HIERARCHY`.
`facetable`	`bool \| null`	Whether this attribute can be used as a facet filter.
`stored`	`bool \| null`	Whether the attribute value is stored in the index.
`level`	`str \| null`	`PARENT` (product level) or `CHILD` (variant level).
`multiValued`	`bool \| null`	Whether a product can have multiple values for this attribute.
`siteId`	`int \| null`	The site ID if the attribute is site-specific, or null for account-level attributes.

get_facet_rule

Fetches the full configuration of a single facet rule by ID. It works for site-search, category, and global facet rules. The response returns every facet action on the rule: boosted and buried facets, always-included facets, excluded facets, associated queries, audience targeting, and scheduling metadata. The customizationItems map holds the facet actions keyed by type: boosted_facets, buried_facets, excluded_facets, and always_included_facets.

Discover rule IDs with list_site_search_facets, list_facets_global, or list_category_facets, then call this tool to inspect a specific rule's full configuration.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the facet rule to fetch. Discover IDs with `list_site_search_facets`, `list_facets_global`, or `list_category_facets`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account. Use `list_discovery_accounts` to see available accounts.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name (string). Defaults to `-1` (account level) when omitted. Use `list_discovery_sites` to discover sites.

Response parameters

The tool returns a CustomizationDetailResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The full facet rule detail as freeform JSON. Includes `id`, `ruleType` (`facet`), `enabled`, `queries`, `customizationItems` (keyed by `boosted_facets`, `buried_facets`, `excluded_facets`, and `always_included_facets`), audience targeting, `startedAt`, `endedAt`, and scheduling metadata.
`error`	`str \| null`	Error message if the request failed.

create_facet_rule

Creates a new facet rule. Facet rules control which filter attributes (facets) appear on search and category pages and how they're ordered. Set each query's queryType to sitesearch with a search term, category with a category ID (find valid IDs with list_categories), or global with query='*' to apply the rule across all pages. One rule can cover multiple categories or search terms when you pass multiple query entries.

The facet parameters map to the dashboard controls: boosted_facets surfaces facets near the top of the filter list, buried_facets pushes them to the end, excluded_facets hides them entirely, and always_included_facets forces them to appear. The boosted_facets and buried_facets lists use 1-based ordering, so the first entry gets position 1. max_count_facets sets the maximum number of facets returned (up to 50) and applies to global rules only. When enabled is true, the rule takes effect after an asynchronous sync to the search index (typically seconds to minutes). Range facet configuration, facet value merging, facet value renaming, per-value reordering, and category facet inheritance aren't available through this tool — use the Discovery dashboard for those. Discover valid attribute names with list_facet_attributes and audience IDs with list_discovery_audiences, then confirm the rule synced with list_site_search_facets, list_category_facets, or list_facets_global.

Request parameters

Name	Type	Required?	Description
`queries`	`list[dict]`	Yes	Queries this rule targets. Pass multiple entries to apply one rule to multiple categories or search terms. Each entry: `query` (a search term, category ID from `list_categories`, or `*` for global), `queryType` (`sitesearch`, `category`, or `global`), and `matchType` (`EXACT_MATCH` or `BROAD`).
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Omit for account level.
`name`	`str \| null`	No	Display name for the rule.
`enabled`	`bool`	No	Whether the rule is active after sync. Defaults to `true`.
`audience_id`	`int \| null`	No	Numeric audience segment ID to scope this rule to a specific audience. Omit for no audience targeting. Discover IDs with `list_discovery_audiences`.
`boosted_facets`	`list[str] \| null`	No	Facet field names to boost near the top of the filter list. Order matters — the first entry gets position 1, for example `['brand', 'color']`. Discover valid names with `list_facet_attributes`.
`buried_facets`	`list[str] \| null`	No	Facet field names to push to the end of the filter list. Order matters, for example `['material', 'weight']`.
`excluded_facets`	`list[str] \| null`	No	Facet field names to hide entirely from the filter list, for example `['warehouse_location', 'internal_sku']`.
`always_included_facets`	`list[str] \| null`	No	Facet field names to always show regardless of the algorithm, for example `['price', 'brand']`.
`max_count_facets`	`int \| null`	No	Global advanced setting: the maximum number of facets returned. Maximum 50. Applies to global rules only.
`facet_items`	`list[dict] \| null`	No	Advanced: raw customization items for types not covered by named parameters, such as `aliases_facets` or `value_configs_facets`. Each entry: `{'customizationType': '<type>', 'customizationValue': '<json-encoded-string>'}`. Merged alongside named parameters by type.
`started_at`	`int \| null`	No	Unix timestamp in milliseconds of when the rule becomes active. Omit for unscheduled.
`ended_at`	`int \| null`	No	Unix timestamp in milliseconds of when the rule expires. Omit for no expiry.

Response parameters

The tool returns a RankingRuleMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The created facet rule as freeform JSON. Use the returned `id` for later update or delete operations.
`error`	`str \| null`	Error message if the operation failed.

update_facet_rule

Updates an existing facet rule. Only the fields you provide change; every other field carries forward from the current rule. The tool fetches the current rule, merges your changes on top, then saves the result. Facet item parameters such as boosted_facets and excluded_facets merge by type, so only the types you specify are replaced while other existing items stay unchanged.

Changes to an enabled rule affect which facets appear for live customers after an asynchronous sync (typically seconds to minutes). Discover the rule ID and confirm its current state with list_site_search_facets, list_category_facets, or list_facets_global before updating.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the facet rule to update. Discover IDs with `list_site_search_facets`, `list_category_facets`, or `list_facets_global`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Omit for account level.
`name`	`str \| null`	No	New display name. Omit to keep the existing name.
`enabled`	`bool \| null`	No	Enable or disable the rule. Omit to keep the existing state.
`audience_id`	`int \| null`	No	Numeric audience segment ID. Omit to keep the existing audience. Discover IDs with `list_discovery_audiences`.
`queries`	`list[dict] \| null`	No	New query list that replaces the existing one. Pass multiple entries to apply the rule to multiple categories or search terms. Each entry: `query` (a category ID, search term, or `*`), `queryType`, and `matchType`. Omit to keep the existing queries.
`boosted_facets`	`list[str] \| null`	No	New list of facet names to boost near the top of the filter list. Order matters — the first entry gets position 1. Replaces the existing list. Omit to keep it.
`buried_facets`	`list[str] \| null`	No	New list of facet names to push to the end of the filter list. Order matters. Replaces the existing list. Omit to keep it.
`excluded_facets`	`list[str] \| null`	No	New list of facet names to hide entirely. Replaces the existing list. Omit to keep it.
`always_included_facets`	`list[str] \| null`	No	New list of facet names to always show. Replaces the existing list. Omit to keep it.
`max_count_facets`	`int \| null`	No	New global maximum number of facets (up to 50). Replaces the existing value. Omit to keep it.
`facet_items`	`list[dict] \| null`	No	Advanced: raw items merged by `customizationType`. Omit to keep the existing items.
`started_at`	`int \| null`	No	New start timestamp in milliseconds. Omit to keep the existing value.
`ended_at`	`int \| null`	No	New end timestamp in milliseconds. Omit to keep the existing value.

Response parameters

The tool returns a RankingRuleMutationResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`data`	`any \| null`	The updated facet rule as freeform JSON.
`error`	`str \| null`	Error message if the operation failed.

delete_facet_rule

Permanently deletes a facet rule. This is irreversible — the rule can't be recovered after deletion, so verify the target before you run it. The rule is removed from live facet display after an asynchronous sync (typically seconds to minutes), not instantly.

If the rule is currently enabled, it's actively shaping which facets appear for shoppers, and deleting it reverts those pages to algorithm defaults once the sync completes. Consider disabling it first with update_facet_rule to preview the impact before permanent removal. Deletion is blocked when the rule is part of a running A/B experiment, where the API returns a Customization is live error; end the experiment first. Discover IDs with list_site_search_facets, list_category_facets, or list_facets_global.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the facet rule to delete. Discover IDs with `list_site_search_facets`, `list_category_facets`, or `list_facets_global`.
`account_name`	`str \| null`	No	The account name. Auto-selected when you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID (numeric) or site name. Omit for account level.

Response parameters

The tool returns a DeleteResponse object with the following parameters:

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