Redirects and API parameters tools

search_redirects: List the query-specific redirect rules, or fetch one by ID.
list_api_params: List the API parameter override rules for an account. Contact your Bloomreach representative for more details on API parameter overrides.
create_redirect: Create a new keyword redirect rule.
update_redirect: Update an existing redirect rule.
delete_redirect: Permanently delete a redirect 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.

search_redirects

Searches query-specific redirect rules, or fetches one by ID. A redirect rule sends a shopper to a specific URL when they search for a particular query; redirects apply to site-search queries only. Omit rule_id to list paginated summaries — each with the name, enabled status, associated queries, and scheduling details.

Pass rule_id to fetch the full configuration, including the destination URL, the match type (exact terms, phrase match, or do-not-redirect), the associated queries and keywords, the enabled status, audience targeting, and scheduling metadata.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int \| null`	No	The redirect rule ID. Omit to list all rules; provide to fetch one.
`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.
`page`	`int`	No	The page number, 0-based. Defaults to `0`. Ignored when `rule_id` is set.
`limit`	`int`	No	Results per page. Defaults to `10`, maximum `100`. Ignored when `rule_id` is set.
`sort_by`	`str`	No	Field to sort by: `lastModifiedAt`, `identifier`, or `duration`. Defaults to `lastModifiedAt`. Ignored when `rule_id` is set.
`sort_order`	`str`	No	Sort direction: `ASC` or `DESC`. Defaults to `DESC`. Ignored when `rule_id` is set.
`q`	`str \| null`	No	Text search to filter rules. Ignored when `rule_id` is set.

Response parameters

The tool returns a CustomizationsResponse object when rule_id is omitted (a list of summaries) or a CustomizationDetailResponse object when rule_id is provided (the full rule).

The CustomizationsResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[CustomizationSummary]`	The redirect 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, for example `redirect`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`durationTag`	`str \| null`	Duration tag: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`startedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule became active.
`endedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule expires.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was created.
`lastModifiedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was last modified.
`lastModifiedBy`	`str \| null`	Email or name of the user who last modified the rule.
`queries`	`list[CustomizationQuery]`	The queries this rule applies to.
`isAbTestLive`	`bool`	Whether an A/B test is currently active for this rule.
`audienceName`	`str \| null`	Name of the audience segment this rule targets.

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

When rule_id is provided, the tool returns a CustomizationDetailResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`any \| null`	The full redirect rule detail as freeform JSON. Includes the destination URL, the match type, the associated queries and keywords, the enabled status, audience targeting, and scheduling metadata.
`error`	`str \| null`	Error message if the request failed.

list_api_params

Lists the API parameter override rules for an account. A parameter override changes the URL parameters sent to the search and category APIs without a change to frontend code. For example, an override can raise the default rows count, add fl (field list) parameters, or force a specific sort order. These rules apply globally across both site-search and category queries.

The tool returns up to 1,000 parameter override rules in a single response.

Request parameters

This tool takes no parameters.

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 API parameter override 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, `params`.
`isEnabled`	`bool \| null`	Whether the rule is currently enabled.
`syncStatus`	`str \| null`	Sync status: `SUCCESS`, `QUEUED`, `FAILED`, `EXPIRED`, or `FUTURE`.
`durationTag`	`str \| null`	Duration tag: `unscheduled`, `scheduled`, `active`, `expiringSoon`, or `expired`.
`startedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule became active.
`endedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule expires.
`createdAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was created.
`lastModifiedAt`	`int \| null`	Unix timestamp in milliseconds of when the rule was last modified.
`lastModifiedBy`	`str \| null`	Email or name of the user who last modified the rule.
`queries`	`list[CustomizationQuery]`	The queries this rule applies to.

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

create_redirect

Creates a new keyword redirect rule. Redirect rules send shoppers to a specific URL instead of showing search results when they type a matching query. Choose a redirect_type: redirect_terms matches an exact keyword and sends shoppers to destination_url, redirect_phrases matches variations of a phrase and sends to destination_url, while do_not_redirect_terms and do_not_redirect_phrases block other redirect rules from firing for matching queries and need no URL. Terms require exact matches; phrases allow partial or fuzzy matches.

The rule goes live after an asynchronous sync (typically seconds to minutes), and each keyword is limited to 255 characters. If a keyword in your queries list already belongs to another redirect rule, Bloomreach silently ignores that keyword in the new rule with no error, so check search_redirects first to avoid silent conflicts. Redirect rules support A/B test variants through create_ranking_rule_variant and create_discovery_experiment, the same way as ranking rules. Use list_discovery_audiences to find audience IDs.

Request parameters

Name	Type	Required?	Description
`queries`	`list[str]`	Yes	Keywords that trigger this redirect, for example `['careers', 'jobs']`. Each string is a search term.
`redirect_type`	`str`	Yes	One of `redirect_terms`, `redirect_phrases`, `do_not_redirect_terms`, or `do_not_redirect_phrases`.
`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.
`destination_url`	`str \| null`	No	URL to redirect shoppers to. Required for `redirect_terms` and `redirect_phrases`. Omit for the `do_not_redirect_*` types.
`name`	`str \| null`	No	Display name for the rule.
`enabled`	`bool`	No	Whether the rule is active immediately after sync. Defaults to `true`.
`audience_id`	`int \| null`	No	Numeric audience segment ID. Discover IDs with `list_discovery_audiences`.
`started_at`	`int \| null`	No	Unix timestamp in milliseconds of when the rule becomes active.
`ended_at`	`int \| null`	No	Unix timestamp in milliseconds of when the rule expires.

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 redirect rule as freeform JSON. Use the returned `id` for later update or delete operations.
`error`	`str \| null`	Error message if the operation failed.

update_redirect

Updates an existing keyword redirect 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. When you provide redirect_type or destination_url, the redirect item is rebuilt accordingly, and changing redirect_type also updates the queries to use the new match type.

Changes to an enabled rule affect live search traffic after an asynchronous sync (typically seconds to minutes). Discover the rule ID and confirm its current state with search_redirects before updating.

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the redirect rule to update. Discover IDs with `search_redirects`.
`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.
`queries`	`list[str] \| null`	No	New keyword list that replaces the existing one. Omit to keep the existing keywords.
`redirect_type`	`str \| null`	No	New redirect type. Omit to keep the existing type. When changed, `destination_url` carries forward from the current rule unless you also provide it.
`destination_url`	`str \| null`	No	New destination URL. Omit to keep the existing URL. Pass an empty string (`''`) to clear it, for example when converting to a `do_not_redirect` type.
`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.
`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 redirect rule as freeform JSON.
`error`	`str \| null`	Error message if the operation failed.

delete_redirect

Permanently deletes a keyword redirect rule. This is irreversible — the rule can't be recovered after deletion, so verify the target before you run it. The rule keeps redirecting shoppers until an asynchronous sync completes (typically seconds to minutes), not instantly.

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

Request parameters

Name	Type	Required?	Description
`rule_id`	`int`	Yes	The ID of the redirect rule to delete. Discover IDs with `search_redirects`.
`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.