There are two search endpoints because there are two questions. Keyword search answers “find this thing”. Semantic search answers “find something that solves this problem”.
If the user typed a model number, use keyword search — it is faster, cheaper and exact. If they described a situation, use semantic search and let it reason about constraints.
// they know what they want
GET /v1/search?q=WH-1000XM5&in_stock=true
// they know the problem, not the product
POST /v1/search/semantic
{ "intent": "quiet vacuum for a small flat with two cats",
"constraints": { "budget_minor": 40000, "must_have": ["hepa"] } }One result is one canonical product with its offers folded in. You do not have to deduplicate four sellers' versions of the same item — that already happened.
Every result carries a verdict computed against that product's own history. Sorting by price alone surfaces the cheapest thing; sorting with the verdict surfaces the best-value thing, which is usually what the user meant.
Semantic search is weighted higher than keyword because it does more work. If you are searching on every keystroke, use suggest for typeahead and reserve semantic for submitted queries.