Synonyms
Synonyms and mined suggestions.
10 endpoints.
GET /v1/synonyms/suggestionsGET /v1/synonyms/suggestions/statusPOST /v1/synonyms/suggestions/{suggestion_id}/decisionGET /v1/synonymsPOST /v1/synonymsGET /v1/synonyms/exportPOST /v1/synonyms/importGET /v1/synonyms/{synonym_id}PUT /v1/synonyms/{synonym_id}DELETE /v1/synonyms/{synonym_id}
GET
/v1/synonyms/suggestionsSynonyms mined from zero-result queries and reformulations
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status | query | "pending" | "approved" | "rejected" | no | default "pending" |
cursor | query | string | null | no | max length 200 |
limit | query | integer | no | default 50 · min 1 · max 200 |
Responses
- 200Successful Response
Page_SynonymSuggestionOut_
GET
/v1/synonyms/suggestions/statusWhen suggestions are made next and what they need
Needs a key or a dashboard session
Responses
- 200Successful Response
SynonymMiningStatus
POST
/v1/synonyms/suggestions/{suggestion_id}/decisionApprove (one click) or reject a suggestion
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
suggestion_id | path | string | yes |
Request body application/json SuggestionDecision
| Name | Type | Required | Description |
|---|---|---|---|
decision | "approve" | "reject" | yes |
Responses
- 200Successful Response
SynonymSuggestionOut
GET
/v1/synonymsList synonyms
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | null | no | max length 200 |
limit | query | integer | no | default 100 · min 1 · max 200 |
q | query | string | null | no | max length 100 |
Responses
- 200Successful Response
Page_SynonymOut_
POST
/v1/synonymsSynonyms Create
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json SynonymIn
| Name | Type | Required | Description |
|---|---|---|---|
kind | "equivalent" | "one_way" | yes | |
terms | string[] | no | equivalent: all match each other. |
input | string | null | no | one_way: this word...max length 200 |
outputs | string[] | no | ...also searches these. |
conditions | SynonymConditions | null | no | |
locale | string | null | no | pattern ^[a-z]{2}$ |
set_key | string | no | Named set (see RankingConfig).default "default" · pattern ^[a-z0-9][a-z0-9_-]{0,31}$ |
enabled | boolean | no | default true |
Responses
- 201Successful Response
SynonymOut
GET
/v1/synonyms/exportExport synonyms
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
format | query | "json" | "csv" | "solr" | no | default "json" |
Responses
- 200Successful Response
string
POST
/v1/synonyms/importSynonyms Import
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json SynonymImport
| Name | Type | Required | Description |
|---|---|---|---|
format | "json" | "csv" | "solr" | no | default "json" |
content | string | yes | The file content.max length 2000000 |
mode | "merge" | "replace" | no | default "merge" |
Responses
- 200Successful Response
SynonymImportResult
GET
/v1/synonyms/{synonym_id}Synonyms Get
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
synonym_id | path | string | yes |
Responses
- 200Successful Response
SynonymOut
PUT
/v1/synonyms/{synonym_id}Synonyms Update
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
synonym_id | path | string | yes |
Request body application/json SynonymIn
| Name | Type | Required | Description |
|---|---|---|---|
kind | "equivalent" | "one_way" | yes | |
terms | string[] | no | equivalent: all match each other. |
input | string | null | no | one_way: this word...max length 200 |
outputs | string[] | no | ...also searches these. |
conditions | SynonymConditions | null | no | |
locale | string | null | no | pattern ^[a-z]{2}$ |
set_key | string | no | Named set (see RankingConfig).default "default" · pattern ^[a-z0-9][a-z0-9_-]{0,31}$ |
enabled | boolean | no | default true |
Responses
- 200Successful Response
SynonymOut
DELETE
/v1/synonyms/{synonym_id}Synonyms Delete
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
synonym_id | path | string | yes |
Responses
- 200Successful Response
Deleted
Data shapes on this page
Page_SynonymSuggestionOut_
| Name | Type | Required | Description |
|---|---|---|---|
data | SynonymSuggestionOut[] | yes | |
next_cursor | string | null | no | |
total | integer | null | no | Present when cheap to count. |
SynonymSuggestionOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
kind | "equivalent" | "one_way" | yes | |
terms | string[] | no | |
input | string | null | no | |
outputs | string[] | no | |
evidence | object | no | Queries and counts that led to it. |
score | number | yes | |
status | "pending" | "approved" | "rejected" | yes | |
created_at | string (date-time) | yes | |
labels | map<string, string> | no | Term (input, outputs, terms) -> the spelling shoppers typed most often, for display. Only terms whose typed spelling differs (e.g. "شنطه" -> "شنطة"); show any other term as it is. |
SynonymMiningStatus
When synonym suggestions are made and what they need (GET /v1/synonyms/suggestions/status). A nightly job mines the store's own searches; a zero-result query becomes a suggestion only when shoppers in at least `min_sessions` different sessions searched it.
| Name | Type | Required | Description |
|---|---|---|---|
schedule | string | yes | Plain text, e.g. "daily at 03:00 UTC". |
next_run_at | string (date-time) | yes | |
last_run_at | string (date-time) | null | no | End of the last run, for every store. |
window_days | integer | yes | Searches of the last N days are used. |
min_sessions | integer | yes | Different shopper sessions a query needs. |
zero_result_queries | integer | yes | Different zero-result queries in the window. |
queries_ready | integer | yes | Zero-result queries with enough sessions for the next run. |
searches_without_session | integer | yes | Zero-result searches sent without a session id (widget `session`, API `session`): never used. |
SuggestionDecision
| Name | Type | Required | Description |
|---|---|---|---|
decision | "approve" | "reject" | yes |
Page_SynonymOut_
| Name | Type | Required | Description |
|---|---|---|---|
data | SynonymOut[] | yes | |
next_cursor | string | null | no | |
total | integer | null | no | Present when cheap to count. |
SynonymOut
| Name | Type | Required | Description |
|---|---|---|---|
kind | "equivalent" | "one_way" | yes | |
terms | string[] | no | equivalent: all match each other. |
input | string | null | no | one_way: this word...max length 200 |
outputs | string[] | no | ...also searches these. |
conditions | SynonymConditions | null | no | |
locale | string | null | no | pattern ^[a-z]{2}$ |
set_key | string | no | Named set (see RankingConfig).default "default" · pattern ^[a-z0-9][a-z0-9_-]{0,31}$ |
enabled | boolean | no | default true |
id | string | yes | |
source | "manual" | "import" | "suggested" | "global_copy" | no | default "manual" |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
SynonymConditions
one_way only. Expand `input` -> `outputs` only when the normalized query passes these checks. Example: dress -> gown, maxi... with unless_terms [bag, hanger, pattern].
| Name | Type | Required | Description |
|---|---|---|---|
unless_terms | string[] | no | Skip if any of these is present. |
require_terms | string[] | no | Apply only if all are present. |
SynonymIn
| Name | Type | Required | Description |
|---|---|---|---|
kind | "equivalent" | "one_way" | yes | |
terms | string[] | no | equivalent: all match each other. |
input | string | null | no | one_way: this word...max length 200 |
outputs | string[] | no | ...also searches these. |
conditions | SynonymConditions | null | no | |
locale | string | null | no | pattern ^[a-z]{2}$ |
set_key | string | no | Named set (see RankingConfig).default "default" · pattern ^[a-z0-9][a-z0-9_-]{0,31}$ |
enabled | boolean | no | default true |
SynonymImport
| Name | Type | Required | Description |
|---|---|---|---|
format | "json" | "csv" | "solr" | no | default "json" |
content | string | yes | The file content.max length 2000000 |
mode | "merge" | "replace" | no | default "merge" |
SynonymImportResult
| Name | Type | Required | Description |
|---|---|---|---|
created | integer | yes | |
updated | integer | yes | |
skipped | integer | yes | |
errors | string[] | no |
Deleted
| Name | Type | Required | Description |
|---|---|---|---|
deleted | boolean | no | default true |
id | string | yes |