Synonyms

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

Type	Behavior	Example
`regular`	Bidirectional — A and B are equivalent	”tenis” ↔ “sneaker”
`one_way`	Unidirectional — 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

Field	Type	Required	Description
`type`	string	Yes	`regular` or `one_way`
`inputTerms`	string[]	Yes	One or more source terms (minimum 1)
`expandedTerms`	string[]	Yes	One 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.

Última modificação em 12 de março de 2026

⌘I

Visão Geral

Workspace

Membros

Marcas

Dashboards

Catálogos

Produtos

Surfaces

Serviços de IA

Faturamento

Chaves de API

Integrações

Reference

Search API v1

Platform Adapters

Analytics

Feed API

MCP Tools

Data Pipeline

Marketplace Hub

Guias de Plataforma

Overview

Synonym Types

Authentication

List Synonyms

Create Synonym

Request Fields

Update Synonym

Delete Synonym

Workspace Isolation

​Overview

​Synonym Types

​Authentication

​List Synonyms

​Create Synonym

​Request Fields

​Update Synonym

​Delete Synonym

​Workspace Isolation

Overview

Synonym Types

Authentication

List Synonyms

Create Synonym

Request Fields

Update Synonym

Delete Synonym

Workspace Isolation