DocumentationSearch Proxy is BYOS: Bring Your Own Search. It gives a site a first-party path for search while SuggestAPI performs retrieval and ranking. Use it when browser clients should call your own domain, when you need a stable public search URL, or when you want to apply controls before a request reaches SuggestAPI.
When to use it
- expose search under your site domain without exposing a private server-side key
- preserve an existing search URL while moving ranking and retrieval to SuggestAPI
- centralize CORS, rate limiting, analytics, and cache policy at your edge
- map a storefront or application route to one SuggestAPI index
Configuration
Create one proxy configuration for each public search surface. The exact controls are managed in the SuggestAPI app; use the following values when setting it up.
| Setting | Purpose | Example |
|---|---|---|
| Public path | The route callers use on your domain. | /api/search |
| Upstream endpoint | The SuggestAPI endpoint to proxy. | /v1/autocomplete |
| Index mapping | The fixed index, or the allowed mapping from request to index. | products |
| Allowed methods | Methods accepted by the proxy. Keep search surfaces read-only. | GET |
| Authentication mode | How the proxy authenticates to SuggestAPI. Keep private credentials at the proxy, not in browser code. | server-side API key |
| Forwarded query fields | The query parameters passed upstream. | query, limit, filters, user_id |
| Cache policy | Whether, where, and for how long successful responses are cached. | cache anonymous GET searches |
| Origin policy | Browser origins permitted to call the path. | https://shop.example.com |
Use a fixed index whenever possible. If you allow the caller to choose an index, explicitly allowlist its values; do not pass arbitrary index IDs through a public route.
Supported paths
Search Proxy is intended for read-only search traffic:
/v1/autocompletefor ranked search results/v1/typeaheadfor fast prefix suggestions
Keep index administration, ingestion, exports, and other mutation routes off the public proxy. Those routes require trusted server-side access and should be called directly from your backend or the SuggestAPI app.
Authentication and headers
The proxy should inject a server-side SuggestAPI credential. Do not put a private key in JavaScript, page markup, or a mobile application bundle.
Pass only the headers your public contract needs. In particular:
- use
X-Bypass-Cacheonly for trusted diagnostics; do not allow untrusted clients to force uncached upstream work - treat
user_idas an identifier subject to your privacy policy - return CORS headers only for approved browser origins
- preserve a request ID in logs so an application request can be correlated with SuggestAPI diagnostics
For the underlying endpoint contracts, see the Search API.