Pular para o conteúdo principal

​
Overview

Synonyms allow you to expand search queries so that related terms find the same products. When a user searches for “tenis”, the search engine can also match “sneaker” and “calcado esportivo” without requiring those exact words in the product catalog. Synonyms are applied automatically during query understanding, before embedding generation. They are cached per workspace with a 5-minute TTL for performance.

​
Synonym Types

TypeBehaviorExample
regularBidirectional — A and B are equivalent”tenis” ↔ “sneaker”
one_wayUnidirectional — A expands to B (but not vice versa)“calcados” → “tenis”, “sapatos”

​
Authentication

All requests require an API key via the x-api-key header. The workspace is resolved from the key.

​
List Synonyms

curl https://alana.shopping/api/v1/synonyms \
  -H "x-api-key: ak_your_api_key"
Response 
{
  "synonyms": [
    {
      "id": "a1b2c3d4-...",
      "workspaceId": "ws-abc",
      "synonymType": "regular",
      "inputTerms": ["tenis"],
      "expandedTerms": ["sneaker", "calcado esportivo"],
      "createdAt": "2026-03-12T10:00:00Z",
      "updatedAt": "2026-03-12T10:00:00Z"
    }
  ],
  "total": 1
}

​
Create Synonym

curl -X POST https://alana.shopping/api/v1/synonyms \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_your_api_key" \
  -d '{
    "type": "regular",
    "inputTerms": ["tenis"],
    "expandedTerms": ["sneaker", "calcado esportivo"]
  }'

​
Request Fields

FieldTypeRequiredDescription
typestringYesregular or one_way
inputTermsstring[]YesOne or more source terms (minimum 1)
expandedTermsstring[]YesOne or more target terms (minimum 1)
Response — 201 Created 
{
  "synonym": {
    "id": "a1b2c3d4-...",
    "workspaceId": "ws-abc",
    "synonymType": "regular",
    "inputTerms": ["tenis"],
    "expandedTerms": ["sneaker", "calcado esportivo"],
    "createdAt": "2026-03-12T10:00:00Z",
    "updatedAt": "2026-03-12T10:00:00Z"
  }
}

​
Update Synonym

curl -X PUT https://alana.shopping/api/v1/synonyms/a1b2c3d4-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_your_api_key" \
  -d '{
    "expandedTerms": ["sneaker", "calcado esportivo", "sapato esportivo"]
  }'
Response — 200 OK with updated synonym record. Returns 404 if the synonym ID does not belong to the workspace (workspace isolation enforced).

​
Delete Synonym

curl -X DELETE https://alana.shopping/api/v1/synonyms/a1b2c3d4-... \
  -H "x-api-key: ak_your_api_key"
Response — 204 No Content on success. 404 if not found.

​
Workspace Isolation

All synonym operations are scoped to the workspace resolved from the API key. It is not possible to read, update, or delete synonyms belonging to another workspace.
Last modified on March 12, 2026