Autosuggest tools

search_autosuggest_exclusion_rules: List the autosuggest exclusion rules in an account, or fetch one by ID.
get_autosuggest_results: Get the autosuggest suggestions for a search term.
create_autosuggest_exclusion_rule: Create a new autosuggest exclusion rule.
update_autosuggest_exclusion_rule: Update an existing autosuggest exclusion rule.
delete_autosuggest_exclusion_rule: Permanently delete an autosuggest exclusion rule.
bulk_update_autosuggest_exclusion_rules: Bulk enable or disable multiple autosuggest exclusion rules.

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

search_autosuggest_exclusion_rules

Searches the autosuggest exclusion rules in an account, or fetches one by ID. Exclusion rules keep specific keywords out of the autosuggest dropdown, so shoppers never see terms you want to hide.

Omit rule_id to list a paginated set of rule summaries, each with the rule name, excluded keywords, domain key, enabled status, and sync status. Pass rule_id to fetch the full detail of a single rule, including its excluded keywords, domain key, enabled status, note, and sync status.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int \| null`	No	The autosuggest rule ID. Omit to list all rules; provide to fetch one.
`account_name`	`str \| null`	No	The account name. Required if you have access to more than one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Defaults to the account level (`-1`).
`page`	`int`	No	The page number, zero-based. Defaults to `0`. Ignored when `rule_id` is set.
`limit`	`int`	No	The number of results per page. Defaults to `10`. Ignored when `rule_id` is set.
`sort_by`	`str`	No	The field to sort by, such as `MODIFIED_AT`, `CREATED_AT`, `RULE_NAME`, or `ENABLED`. Defaults to `MODIFIED_AT`. Ignored when `rule_id` is set.
`sort_order`	`str`	No	The sort direction, `ASC` or `DESC`. Defaults to `DESC`. Ignored when `rule_id` is set.
`q`	`str \| null`	No	A text search to filter rules by name, user, or keywords. Ignored when `rule_id` is set.

Response parameters

The tool returns an AutosuggestRulesResponse object when rule_id is omitted (a list of summaries) or an AutosuggestRuleResponse object when rule_id is provided (a single rule's full detail).

The AutosuggestRulesResponse object has the following parameters:

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

The AutosuggestRule object has the following fields:

Field	Type	Description
`id`	`int`	The rule's unique ID.
`accountId`	`int \| null`	The account this rule belongs to.
`domainKey`	`str \| null`	The domain key the rule applies to. A `null` value means account-wide.
`ruleName`	`str \| null`	The rule's display name.
`keywords`	`list[str]`	The keywords excluded from autosuggest.
`enabled`	`bool`	Whether the rule is enabled.
`note`	`str \| null`	An optional note, up to 255 characters.
`user`	`str \| null`	The user who last modified the rule.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was created.
`modifiedAt`	`int \| null`	Unix timestamp in milliseconds of the last modification.
`deleted`	`bool \| null`	Whether the rule has been soft-deleted.
`deletedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was deleted.
`syncStatus`	`str \| null`	The sync status: `PENDING`, `IN_PROGRESS`, `SUCCESS`, or `FAILED`.

When rule_id is provided, the tool returns an AutosuggestRuleResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`AutosuggestRule \| null`	The full exclusion rule record.
`error`	`str \| null`	Error message if the request failed.

The AutosuggestRule object in the detail response has the same fields listed above.

get_autosuggest_results

Returns the search terms that would appear in the autosuggest dropdown when a shopper starts typing a query. Use this to test how autosuggest behaves for a given term, confirm that your exclusion rules work, or explore what terms surface for a partial query.

Request parameters

Name	Type	Required?	Description
`q`	`str`	Yes	The search term to get suggestions for.
`domain_key`	`str \| null`	No	The domain key to query. Omit to use the merchant default.

Response parameters

The tool returns an AutosuggestSuggestionsResponse object with the following parameters:

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

create_autosuggest_exclusion_rule

Creates a new autosuggest exclusion rule. Exclusion rules keep specific keywords out of the autosuggest dropdown, so shoppers never see the terms you want to hide. Exclusion is global across all queries, so excluding shoes suppresses it no matter what a shopper types. Autosuggest exclusion rules are managed at the account level only. The site_group_id parameter is accepted for authentication but doesn't scope the rule to a specific site, and domain_key set to null applies the rule across all catalogs.

The rule syncs automatically after creation, which takes seconds to minutes, so it isn't live immediately. Set enabled to False to stage a rule before activating it. After creating, confirm the sync with search_autosuggest_exclusion_rules and preview the effect with get_autosuggest_results.

Request parameters

Name	Type	Required?	Description
`rule_name`	`str`	Yes	The display name for the exclusion rule, up to 255 characters.
`keywords`	`list[str]`	Yes	The autosuggest suggestions to exclude, such as `['sale items', 'clearance sale']`. These exact suggestions are suppressed from the dropdown.
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Omit for account-level.
`domain_key`	`str \| null`	No	A catalog domain key to scope the rule to a specific catalog, such as `your_domain_com`. Omit for account-wide exclusions across all catalogs.
`note`	`str \| null`	No	An optional description of the rule, up to 255 characters.
`enabled`	`bool`	No	Whether the rule is active immediately after sync. Defaults to `true`. Set `false` to stage before activating.

Response parameters

The tool returns an AutosuggestMutationResponse object with the following parameters:

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

update_autosuggest_exclusion_rule

Updates an existing autosuggest exclusion rule. This is a true partial update, so only the fields you provide are changed and omitted fields are left unchanged without needing to fetch the current state first. You can update the rule name, keywords, enabled state, or note independently. Passing keywords replaces the existing keyword list entirely rather than adding to it.

Use search_autosuggest_exclusion_rules to confirm the rule ID and its current state before updating. As with exclusion rules generally, the operation is account-scoped, and changes sync automatically after the update in seconds to minutes.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the rule to update. Use `search_autosuggest_exclusion_rules` to find IDs.
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Omit for account-level.
`rule_name`	`str \| null`	No	A new display name. Omit to keep the existing name.
`keywords`	`list[str] \| null`	No	A new list of excluded suggestions, which replaces the existing list entirely. Omit to keep the existing list.
`enabled`	`bool \| null`	No	Enable or disable the rule. Omit to keep the existing state.
`note`	`str \| null`	No	A new note or description. Omit to keep the existing note.

Response parameters

The tool returns an AutosuggestMutationResponse object with the following parameters:

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

delete_autosuggest_exclusion_rule

Permanently deletes an autosuggest exclusion rule. This is irreversible, with no undo, so verify the target with search_autosuggest_exclusion_rules before you delete. The platform uses a soft delete, so the record is marked deleted rather than physically removed, and the rule stays active until the next asynchronous sync completes in seconds to minutes.

The operation is account-scoped. The site_group_id parameter is accepted for authentication but doesn't scope the operation to a specific site.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the rule to delete. Use `search_autosuggest_exclusion_rules` to find IDs.
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID 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.

bulk_update_autosuggest_exclusion_rules

Enables or disables multiple autosuggest exclusion rules in a single call. The tool returns a per-rule breakdown of successes and failures, so partial success is possible. Already-deleted rules are reported as failures without stopping the operation, so always check the failure map to see which rules didn't process.

Use search_autosuggest_exclusion_rules to find the rule IDs you want to update. Changes sync automatically after the operation.

Request parameters

Name	Type	Required?	Description
`rule_ids`	`list[int]`	Yes	The autosuggest rule IDs to enable or disable.
`action`	`str`	Yes	The action to perform: `ENABLE` to activate rules or `DISABLE` to deactivate them.
`account_name`	`str \| null`	No	The account name. Auto-selected if you have exactly one account.
`site_group_id`	`str \| int \| null`	No	A site group ID or site name. Omit for account-level.

Response parameters

The tool returns an AutosuggestBulkResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the bulk operation was accepted.
`data`	`AutosuggestBulkResult \| null`	The per-rule breakdown of the operation.
`error`	`str \| null`	Error message if the operation failed.

The AutosuggestBulkResult object has the following fields:

Field	Type	Description
`success`	`list[int]`	The IDs of the rules that were successfully processed.
`failure`	`any \| null`	A map of rule ID to failure reason for rules that couldn't be processed, such as already-deleted rules.