Suggestions
Suggestions are as-you-type search: the suggest endpoint returns matching records after every keystroke, so a search box can show results the instant someone starts typing. It’s the same idea as full search, tuned for partial, in-progress queries — fast, prefix-aware and typo-tolerant — and it’s what powers the autocomplete component. This is an API feature; the worked requests below are the reference.
Suggest against a list
The query text goes in the path (not the query string), after the list and version:
GET https://api.searchstack.dev/suggest/{account}/{list}/{version}/{query}So a user who has typed “incep” into your box triggers:
GET https://api.searchstack.dev/suggest/acme/movies/3/incepSuggest across a group
Exactly like full search, suggestions can fan out over every list in a group — supply the group’s membership version in the path:
GET https://api.searchstack.dev/suggest/group/{account}/{group}/{version}/{query}Narrow and shape the results
A few query-string options refine what comes back (the POST variants of each endpoint take the same settings as a JSON body):
| Option | What it does |
|---|---|
size | How many suggestions to return (keep it small for a typeahead — 5–8 is typical). |
filter | A facet filter, same grammar as full search — e.g. suggest only in_stock eq true products. |
radius | Restrict to records near a point (latitude,longitude,distance) for location-aware typeahead. |
cache | Set false to bypass the cache when you need the very latest records. |
GET https://api.searchstack.dev/suggest/acme/products/2/run?size=6&filter=in_stock%20eq%20trueResponse
The response is a ranked array of records — the matches for the partial query, best first — each with its searchable, facet and resource fields, ready to render as a dropdown:
[
{ "name": "Inception", "list_name": "movies", "year": 2010, "image_url": "https://cdn.acme.example/inception.jpg" },
{ "name": "Insidious", "list_name": "movies", "year": 2010, "image_url": "https://cdn.acme.example/insidious.jpg" }
]Use the component instead of calling it yourself
You rarely need to call suggest by hand. The @searchstack/autocomplete component wires an ordinary <input> to this endpoint for you — debouncing keystrokes, cancelling stale requests, handling keyboard navigation and rendering each row with your own template. Point it at a list or group and you get a production-ready typeahead in a few lines.
Where the suggestions come from
Suggestions are drawn from whatever records are in the list (or group) you point at. Often that’s your real data — suggest over your products list and users get product typeahead. But you can also build a dedicated list of search phrases and suggest over that. User Generated Suggestions fills such a list automatically, capturing the phrases your users successfully search so your typeahead learns from real usage.
A worked example
Your storefront has a products list. You drop the autocomplete component onto your search box, pointed at products, with a filter of in_stock eq true and size: 6. As a shopper types “wat”, the component calls suggest/…/wat, gets back six in-stock matches — waterproof jackets, water bottles — and renders them with your template, each linking straight to the product. The shopper finds what they want before finishing the word, and never sees an out-of-stock result.