Search Synonyms

Synonyms let you expand search queries so customers find products even when they use different terminology. For example, mapping “tee” to “t-shirt” ensures both terms return the same results.

Two synonym types are supported:

• Equivalent (two-way): all terms match each other. Searching for any term returns results for all terms.
• One-way: the first term expands to include the remaining terms, but not the reverse.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/search/synonyms	Secret	List synonyms
POST	/v1/search/synonyms	Secret	Create a synonym
PATCH	/v1/search/synonyms/{id}	Secret	Update a synonym
DELETE	/v1/search/synonyms/{id}	Secret	Delete a synonym

---

List synonyms

GET /v1/search/synonyms

Returns all synonym mappings for the store.

Query parameters

Parameter	Type	Description
fields	string	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/search/synonyms \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "syn_abc123def456ghij",
			"synonym_type": "equivalent",
			"terms": ["t-shirt", "tee", "tshirt"],
			"is_active": true,
			"created_at": "2026-02-10T11:00:00.000Z",
			"updated_at": "2026-02-10T11:00:00.000Z"
		},
		{
			"id": "syn_klm789nop012qrst",
			"synonym_type": "oneway",
			"terms": ["sneakers", "trainers"],
			"is_active": true,
			"created_at": "2026-03-05T09:30:00.000Z",
			"updated_at": "2026-03-05T09:30:00.000Z"
		}
	]
}

---

Create a synonym

POST /v1/search/synonyms

Creates a synonym mapping. The synonym cache is invalidated automatically after creation.

Request body

Field	Type	Required	Default	Description
synonym_type	string	No	"equivalent"	"equivalent" (two-way) or "oneway"
terms	string[]	Yes	-	List of synonym terms (2-20 items, 1-100 chars each)

Request

curl -X POST https://api.hydrajs.dev/v1/search/synonyms \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "synonym_type": "equivalent",
    "terms": ["t-shirt", "tee", "tshirt"]
  }'

Response 201

{
	"data": {
		"id": "syn_abc123def456ghij",
		"synonym_type": "equivalent",
		"terms": ["t-shirt", "tee", "tshirt"],
		"is_active": true,
		"created_at": "2026-02-10T11:00:00.000Z",
		"updated_at": "2026-02-10T11:00:00.000Z"
	}
}

---

Update a synonym

PATCH /v1/search/synonyms/{id}

Updates a synonym mapping. The synonym cache is invalidated automatically after modification.

Request body

Field	Type	Required	Description
synonym_type	string	No	"equivalent" or "oneway"
terms	string[]	No	Updated list of terms (2-20 items)
is_active	boolean	No	Enable or disable the synonym mapping

Request

curl -X PATCH https://api.hydrajs.dev/v1/search/synonyms/syn_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Response 200

{
	"data": {
		"id": "syn_abc123def456ghij",
		"synonym_type": "equivalent",
		"terms": ["t-shirt", "tee", "tshirt"],
		"is_active": false,
		"created_at": "2026-02-10T11:00:00.000Z",
		"updated_at": "2026-08-17T14:00:00.000Z"
	}
}

---

Delete a synonym

DELETE /v1/search/synonyms/{id}

Permanently deletes a synonym mapping. The synonym cache is invalidated automatically.

Request

curl -X DELETE https://api.hydrajs.dev/v1/search/synonyms/syn_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

The synonym object

Field	Type	Description
id	string	Unique ID (prefix: syn_)
synonym_type	string	"equivalent" (two-way) or "oneway" (one-way)
terms	string[]	List of synonym terms
is_active	boolean	Whether the synonym mapping is active
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp