Skip to main content

Synonyms API

Overview​

A synonym group rewrites searches for any of its child phrases to its parent phrase. A search whose whole query equals a child (case-insensitively, ignoring leading and trailing whitespace) runs as a search for the parent, and gets the parent's search rules. Searching for the parent is not expanded to its children.

For example, a group with parent running shoes and children runners and trainers makes a search for Trainers return the results and merchandising of running shoes.

MethodPathDescription
GET/synonymsList synonym groups
POST/synonymsCreate a synonym group
GET/synonyms/groups/{parent}Get a group
PATCH/synonyms/groups/{parent}Add or remove children
DELETE/synonyms/groups/{parent}Delete a group
GET/synonyms/phrases/{phrase}Find the group a phrase belongs to

Paths are relative to https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise. Encode {parent} and {phrase} as one path segment (see Triggers in the path). Both are case-insensitive.

Synonym group fields​

FieldTypeDescription
parentstringThe phrase searches are rewritten to. Up to 200 characters.
childrenstring[]1 to 50 phrases, each up to 200 characters, rewritten to the parent. Unique case-insensitively, and must not include the parent.
revisionstringRead-only. See Revisions.

Phrases are matched canonically (edge whitespace removed, lower-cased, Unicode-normalised), but stored and returned as you wrote them, so Running Shoes keeps its capitals.

Rules​

  • A phrase belongs to at most one group, and a parent can't also be a child. Using a phrase that is in another group is 409 phrase_in_use, naming the phrase.
  • A phrase that has its own search rules, or a search facet override set in the console, can't become a child (409 child_has_rules): once it is a child, those rules would never apply. Move or delete them first.
  • Phrases holding control characters, or characters no search query can contain, are 400 validation_error.
  • Rules stored under the parent stay with it when the group changes or is deleted.

List synonym groups​

Endpoint: GET /synonyms

Ordered by parent, case-insensitively.

Query parameterDescription
searchOptional case-insensitive prefix, matched against parents and children. Up to 200 characters.
limitGroups per page, 1 to 25. Defaults to 10.
cursorThe nextCursor from the previous page.
curl "https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms?search=run&limit=25" \
-H "Authorization: Bearer {api_key}"
{
"items": [
{
"parent": "running shoes",
"children": ["runners", "trainers", "jogging shoes"],
"revision": "4b7e19c2a0d84f6e9b3c5a1d2e7f8091"
}
],
"nextCursor": null
}

Create a synonym group​

Endpoint: POST /synonyms

curl -X POST https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"parent": "running shoes",
"children": ["runners", "trainers", "jogging shoes"]
}'

Returns 201 with the created group. If a group with the same parent exists:

  • with the same children (compared canonically, in any order), the request returns 200 with the stored group, so a retried create succeeds;
  • otherwise it fails with 409 already_exists.

If-Match and If-None-Match are refused with 400 validation_error.

Get a synonym group​

Endpoint: GET /synonyms/groups/{parent}

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/groups/running%20shoes \
-H "Authorization: Bearer {api_key}"

Returns the group, or 404 synonym_group_not_found.

Add or remove children​

Endpoint: PATCH /synonyms/groups/{parent}

FieldDescription
addPhrases to add as children. Up to 50, each up to 200 characters.
removePhrases to remove. Up to 50.
curl -X PATCH https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/groups/running%20shoes \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"add": ["sneakers"],
"remove": ["jogging shoes"]
}'

Returns the updated group.

  • Adding a phrase that is already a child, or removing one that isn't, is a no-op, so a retried PATCH succeeds.
  • Added children are checked as on create.
  • A group must keep at least one child, and can have at most 50; to remove every child, delete the group.
  • One PATCH can change at most 97 children in total (real additions plus real removals); split larger changes.
  • Takes an optional If-Match. A missing group is 404 synonym_group_not_found whatever If-Match says.
  • 409 ambiguous_synonym_group: the group was stored with children that differ only in case, accents or whitespace. Delete it and create it again.

Delete a synonym group​

Endpoint: DELETE /synonyms/groups/{parent}

curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/groups/running%20shoes \
-H "Authorization: Bearer {api_key}"

Returns 204. The children stop being rewritten; rules stored under the parent stay. Returns 404 synonym_group_not_found if the group doesn't exist, including on a retry. Takes an optional If-Match.

Look up a phrase​

Endpoint: GET /synonyms/phrases/{phrase}

Finds whether a phrase is a parent or a child, and of which group.

curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/synonyms/phrases/trainers \
-H "Authorization: Bearer {api_key}"
{
"role": "child",
"phrase": "trainers",
"parent": "running shoes"
}

parent is set only when role is child. A phrase in no group returns 404 synonym_group_not_found.

Renaming a parent​

The API has no rename. To rename a parent:

  1. Delete the old group.
  2. Create a group with the new parent and the same children.
  3. Move the old parent's search rules: GET them, remove trigger from the body (it must match the path), PUT the body to the new parent, then DELETE them from the old parent.

The old parent can't become a child of the new group while it still has its own rules (409 child_has_rules), so move the rules before adding it.

The steps aren't atomic, so the children briefly aren't rewritten. The console's rename does this in one step.

note

Marqo may create internal synonym groups on your index. They are not listed and return 404 through the API, but they still serve and take part in conflict checks, so a conflict message can name an internal group's parent.