Retrieval abstraction
Query routing, lexical vs embedding, and intent-to-API mapping.
Companion to The OpenRouter for Search. One acceleration layer sits in front of Algolia, Typesense, Elastic, or Meilisearch and decides how a query is rewritten, which retriever runs, and which API surface answers.
Query routing
Routing is not “pick a vendor.” It is classifying the request, rewriting it, then sending it to the index and retriever that can answer it. The client always calls SuggestAPI; the backend can change without a new integration.
Classify
What is this query trying to do?
Prefix typeahead, navigational brand, attribute filter, comparison, or a full information request. That label picks the endpoint family: autocomplete, query, compare, or recommend.
Rewrite
Correct, expand, then log both forms
Spell correction and synonym expansion happen at the edge before origin search. Responses keep original_query and corrected_query so agents can show what they searched.
Dispatch
Adapter + cache + fallback
Per-index routing selects Algolia, Typesense, Elastic, Meilisearch, or a SuggestAPI index. Cache hits never touch origin. Failover is a routing rule, not a client retry storm.
Lexical vs embedding retrieval
Ecommerce search needs both. Lexical matching protects SKUs, GTIN, and exact attributes. Embeddings recover paraphrases and messy agent language. Hybrid ranking is the default, not a research extra.
| Signal | Lexical / keyword | Embedding / semantic | Use when |
|---|---|---|---|
| SKU, GTIN, model number | Exact and prefix match | Weak; IDs are not language | Agent pasted an identifier |
| “waterproof hiking boots size 11” | Tokens + filters (size, waterproof) | Paraphrases (“gore-tex trail shoe”) | Hybrid: filters from lexical, recall from vectors |
| Typos and prefixes | Typeahead, n-grams, typo tolerance | Slow and noisy on short prefixes | Autocomplete stays lexical-first |
| Latency | Milliseconds at the edge | Higher unless cached | Cache semantic results; don’t embed every keystroke |
Intent-to-API mapping
Agents should not send every utterance to one search box. Map intent to the surface that returns the right shape: suggestions, hits, comparisons, or a checkout handoff.
| User / agent intent | API surface | Why |
|---|---|---|
| Typing “bo…” in a search bar | GET /v1/autocomplete | Prefix, typo, and merchandised suggestions — not a full result page |
| “Find waterproof hiking boots under $200” | POST /query or POST /v1/agent/search | Full retrieval with filters, rewrite, and ranked products |
| “Which of these two jackets is lighter?” | POST /v1/agent/compare | Structured attribute diff, not a new keyword search |
| “More like this SKU” | POST /v1/agent/recommend | Item-to-item retrieval, not a paraphrased query |
| “Add it to my cart” | Handoff URL from the search/compare payload | Checkout stays on the merchant; SuggestAPI does not take payment |
Discover those agent surfaces from the ARD agent reference. Wire storefront autocomplete through Bring Your Own Search.
Essay
The OpenRouter for Search
Why retrieval needs an abstraction layer — one API to route, normalize, and accelerate search.
Agents
Search plus intent
Why agents fail when they retrieve without ranking for intent.
Understanding
Query, user, and domain
The three intent dimensions behind rewrite and ranking.
Ready to add agentic commerce to your storefront?
Join the waitlist to put query routing, hybrid retrieval, and agent search in front of the engine you already run.