SuggestAPISuggestAPIDocumentation
Contact usOpen app
Features

Search Proxy

Bring your own search — either proxy live autocomplete to your engine (hosted ranking off) or put a first-party path in front of SuggestAPI hosted search.

Copy page
Open in ChatGPTOpen with page contextOpen in ClaudeOpen with page context

Search Proxy covers two related BYOS patterns.

Search proxy mode (Manage Settings → Your search API) is tenant search serving: SuggestAPI accepts /v1/autocomplete and /v1/typeahead and forwards them to your search API. Retrieval and ranking happen on that engine. Hosted SuggestAPI search behavior is not applied. What you lose is listed in Search capabilities. Configure the connection in Search serving.

Site proxy to SuggestAPI is the other pattern: a first-party path on your domain forwards read-only search to SuggestAPI, and SuggestAPI still ranks. Use that when browser clients should call your own host while hosted hybrid search, merchandising, and personalization stay in effect.

When to use a site proxy to SuggestAPI

  • 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 at your edge or reverse proxy. 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/autocomplete for ranked search results
  • /v1/typeahead for 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-Cache only for trusted diagnostics; do not allow untrusted clients to force uncached upstream work
  • treat user_id as 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. For tenant search proxy mode (your engine ranks), see Search serving and Search capabilities.