Synonyms
Synonyms and mined suggestions.
9 endpoints.
GET /v1/synonyms/suggestionsPOST /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_
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 |
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 (gates.md fix 1): laptop -> thinkpad, ideapad... with unless_terms [bag, sleeve, charger].
| 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 |