Synonyms tools

list_synonyms_user: List the synonyms created by your team.
list_synonyms_br_generated: List the automatically generated synonym suggestions.
create_synonym: Create a new user synonym rule.
update_synonym: Update an existing user synonym rule.
delete_synonym: Permanently delete a user synonym 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_synonyms_user

Lists the synonyms your team has created by hand. Synonyms expand search recall by mapping terms that shoppers treat as equivalent. For example, mapping sneakers to shoes returns the same results for either term.

Synonyms can be one-way, where the source term maps to the target but not the reverse, or grouped, where every term in the group is treated as equivalent. This tool returns user synonyms account-wide by default, or scoped to a site through site_group_id. For automatically generated suggestions, use list_synonyms_br_generated.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	The page number, zero-based. Defaults to `0`. Use `-1` to fetch all synonyms in one request.
`limit`	`int`	No	The number of results per page. Defaults to `10`.
`sort_by`	`str`	No	The field to sort by. Defaults to `LAST_MODIFIED_DATE`.
`sort_order`	`str`	No	The sort direction, `ASC` or `DESC`. Defaults to `DESC`.

Response parameters

The tool returns a SynonymsResponse object with the following parameters:

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

The SynonymSummary object has the following fields:

Field	Type	Description
`id`	`int`	The synonym's unique ID.
`merchantId`	`int \| null`	The merchant this synonym belongs to.
`sourceSynonym`	`str \| null`	The source term.
`targetSynonym`	`str \| null`	The target term.
`enabled`	`bool \| null`	Whether the synonym is enabled.
`groupSynonym`	`bool \| null`	Whether this is a group (bidirectional) synonym.
`synonymType`	`str \| null`	The synonym type, such as `USER_CREATED`.
`lastModifiedDate`	`int \| null`	Unix timestamp of when the synonym was last modified.
`lastModifiedBy`	`str \| null`	The user who last modified the synonym.
`siteGroupId`	`int \| null`	The site group ID. A `null` value means account-wide.

list_synonyms_br_generated

Lists the synonym suggestions generated automatically from observed search behavior. The AI identifies terms that shoppers use interchangeably, based on their queries and clicks, and proposes them as synonyms. Merchandisers can then review, enable, or disable each suggestion.

The response gives you paginated synonym summaries. For synonyms your team created by hand, use list_synonyms_user.

Request parameters

Name	Type	Required?	Description
`page`	`int`	No	The page number, one-based. Defaults to `1`.
`per_page`	`int`	No	The number of results per page. Defaults to `10`.
`sort_by`	`str`	No	The field to sort by. Defaults to `lastModifiedDate`.
`sort_order`	`str`	No	The sort direction, `Asc` or `Desc`. Defaults to `Desc`.

Response parameters

The tool returns a SynonymsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[SynonymSummary]`	The automatically generated synonyms.
`error`	`str \| null`	Error message if the request failed.

The SynonymSummary object has the following fields:

Field	Type	Description
`id`	`int`	The synonym's unique ID.
`merchantId`	`int \| null`	The merchant this synonym belongs to.
`sourceSynonym`	`str \| null`	The source term.
`targetSynonym`	`str \| null`	The target term.
`enabled`	`bool \| null`	Whether the synonym is enabled.
`groupSynonym`	`bool \| null`	Whether this is a group (bidirectional) synonym.
`synonymType`	`str \| null`	The synonym type, set to `BR_GENERATED_SITE`.
`lastModifiedDate`	`int \| null`	Unix timestamp of when the synonym was last modified.
`lastModifiedBy`	`str \| null`	The user who last modified the synonym.
`siteGroupId`	`int \| null`	The site group ID.

create_synonym

Creates a new user synonym rule. Synonyms broaden search recall by mapping terms that shoppers treat as equivalent, so a query for one term also matches products indexed under the others. A one-way synonym, the default, expands a source term to its targets, so searching dress also returns results for gown and frock. A two-way synonym, set with group_synonym to True, treats every term as equivalent in both directions. For a two-way synonym, list all terms comma-separated in source_synonym and leave target_synonym empty.

Each individual term must be fewer than four words, and you shouldn't wrap terms in quotes. Capitalization doesn't matter, so there's no need to create case variants. For multisite accounts, always create synonyms at the account level by omitting site_group_id, since synonyms created at the view level don't sync to the front end even when the status shows green. Synonyms sync to the search index once per hour in production, so the rule isn't live immediately. Confirm it synced with list_synonyms_user.

Request parameters

Name	Type	Required?	Description
`source_synonym`	`str`	Yes	For a one-way synonym, the search term shoppers enter, such as `dress`. For a two-way synonym, all terms comma-separated, such as `kids,children,toddler`.
`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 for site-specific synonyms. Omit for account-level, which is recommended. For multisite accounts, always create at the account level.
`target_synonym`	`str \| null`	No	Comma-separated expansion terms for a one-way synonym, such as `gown,frock,sundress`. Omit or leave empty for a two-way synonym.
`group_synonym`	`bool`	No	`False`, the default, creates a one-way directional synonym. `True` creates a two-way bidirectional synonym.
`enabled`	`bool`	No	Whether the synonym is active. Defaults to `true`.

Response parameters

The tool returns a SynonymMutationResponse object with the following parameters:

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

update_synonym

Updates an existing user synonym rule. You can change the synonym terms, switch between one-way and two-way, or enable and disable the rule. Use list_synonyms_user to confirm the synonym ID and its current terms before updating. As with creation, each term must be fewer than four words with no quotes, and changes sync to the search index once per hour rather than immediately.

User Modified synonyms, which are BR-generated synonyms that were edited or disabled, can be updated, but their synonymType stays User Modified rather than changing to User Created.

Request parameters

Name	Type	Required?	Description
`synonym_id`	`int`	Yes	The ID of the synonym to update. Use `list_synonyms_user` to find IDs.
`source_synonym`	`str`	Yes	The updated source term for a one-way synonym, or all comma-separated terms for a two-way synonym. Each term must be fewer than four words.
`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. Omit for account-level.
`target_synonym`	`str \| null`	No	Comma-separated expansion terms for a one-way synonym. Omit or leave empty for a two-way synonym.
`group_synonym`	`bool`	No	`False` for a one-way synonym, `True` for a two-way synonym.
`enabled`	`bool`	No	Enable or disable the synonym.

Response parameters

The tool returns a SynonymMutationResponse object with the following parameters:

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

delete_synonym

Permanently deletes a user synonym rule. This is irreversible, with no undo, so verify the target with list_synonyms_user before you delete. The synonym stays active until the next hourly sync, so removal isn't instant.

Only User Created synonyms can be permanently deleted. If a synonym has synonymType of User Modified, the platform moves it back to the BR Generated tab and re-enables it instead of deleting it, and BR Generated synonyms can't be deleted at all. Check the type with list_synonyms_user first.

Request parameters

Name	Type	Required?	Description
`synonym_id`	`int`	Yes	The ID of the synonym to delete. Use `list_synonyms_user` to find IDs and check `synonymType`.
`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. 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.