Bring your own search

BYOS integration reference

Keep Algolia, Typesense, Elasticsearch, or Meilisearch as your index. Point clients at SuggestAPI; we rewrite, cache, route, and normalize responses from the engine underneath.

Join waitlist OpenAPI spec API reference

Request path

Phase	What happens
Edge ingress	Client sends `GET /v1/autocomplete` or `POST /query` with a SuggestAPI key. TLS terminates at the edge; rate limits and request validation run before origin work.
Normalize & rewrite	Query string is trimmed, spell-corrected, and expanded when `rewrite=true`. SuggestAPI records `original_query`, `corrected_query`, and `expanded_query` on the response.
Cache lookup	Hot autocomplete keys are served from edge cache when `cache=true` and the index/backend tuple is cacheable. Misses fall through to the configured adapter.
Adapter route	Per-index routing selects the backend adapter (`algolia`, `typesense`, `elastic`, `meilisearch`, or `suggestapi`). Backend credentials are injected server-side — never returned to the client.
Response map	Adapter hits are normalized into one JSON schema (`suggestions[]` with `id`, `type`, `title`, `subtitle`, `url`, etc.) regardless of upstream engine shape.

Examples

Autocomplete (storefront default)

curl "https://api.suggestapi.com/v1/autocomplete" \
  -G \
  --data-urlencode "index=products" \
  --data-urlencode "query=waterprof boots" \
  --data-urlencode "limit=8" \
  --data-urlencode "rewrite=true" \
  -H "x-api-key: $SUGGESTAPI_KEY"

Replace direct search client calls with this single GET. Adapter routing is configured per index in SuggestAPI — not in the request.

Full query

curl -X POST "https://api.suggestapi.com/query" \
  -H "Authorization: Bearer $SUGGESTAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "products",
    "query": "waterproof hiking boots",
    "rewrite": true,
    "cache": true
  }'

SuggestAPI resolves the upstream engine from your index config after the request hits api.suggestapi.com. Clients send query + index only.

Endpoint families

Method	Path	Use	Key params
GET	/v1/autocomplete	Typeahead and search-bar suggestions. Primary BYOS integration surface for storefronts.	`index`, `query`, `limit`, optional `rewrite`, `cache`
GET	/v1/typeahead	Prefix-oriented completion when you want lighter payloads than full autocomplete.	`index`, `query`, `limit`
POST	/query	Full search queries with rewrite, cache, and filters. Adapter routing is resolved from your index configuration.	`index`, `query`, `rewrite`, `cache`, filters

Health check: /health

Response schema

{
  "query": "waterproof hiking boots",
  "original_query": "waterprof boots",
  "corrected_query": "waterproof boots",
  "expanded_query": "waterproof hiking boots",
  "mode": "autocomplete",
  "suggestions": [
    {
      "id": "sku-8842",
      "type": "product",
      "title": "Men's Waterproof Hiking Boots",
      "subtitle": "Gore-Tex · size 10",
      "url": "/products/sku-8842"
    }
  ]
}

Field	Meaning
query	Normalized query SuggestAPI processed
original_query	Raw input from the client before rewrite
corrected_query	Spell-corrected form when rewrite changed the string
mode	Suggestion mode (`autocomplete`, `typeahead`, etc.)
suggestions[]	Normalized hits — same shape whether upstream was Algolia or Typesense
live	Whether the response came from a live adapter or static fallback (demo routes only)

Trust boundary

Scope	Holds	Never sees
Browser / mobile / agent client	SuggestAPI API key (`x-api-key` or `Authorization: Bearer`)	Algolia admin key, Typesense API key, Elastic credentials
SuggestAPI edge + control plane	Backend adapter credentials, per-index routing rules, cache keys, analytics events	End-user PII unless you send it in query params
Your search backend	Index documents, ranking config, synonym rules, replica topology	Other tenants, unrelated indexes, client-side secrets

Adapter configuration

Map each SuggestAPI `index` slug to one backend adapter and upstream index name.
Store Algolia / Typesense / Elastic credentials in SuggestAPI — not in your SPA bundle or agent manifest.
Point staging at Typesense and production at Algolia by changing index routing, not client code.
Run shadow traffic: duplicate queries to a candidate backend and compare latency or hit quality in analytics.

Operations

Cache behavior

Autocomplete with cache=true serves repeat prefixes from the edge. TTL is index-scoped; bust cache when you bulk-reindex upstream.

Failure modes

Adapter timeouts or 5xx responses surface as degraded suggestions — configure fallbacks per index. Rate limits return sample or cached payloads rather than exposing upstream errors to clients.

Observability

Every routed query emits analytics: raw query, rewrite delta, backend adapter, latency, and click-through when you wire the tracking pixel or server-side events.

agents.md Product overview