Skip to content
AutoSuggesAutoSugges home
Start free
Menu
Appearance
Appearance: System.

GET /v1/query — the autocomplete endpoint

Call the runtime Worker directly for pre-ranked autocomplete suggestions — the endpoint every SDK binding calls underneath.

What this endpoint does

A correct raw HTTP call to GET /v1/query: the right key placement, a normalized query, the real response shape, and every error code this route can return handled by its code, not by guessing at a message.

Before you call it

  • An AutoSugges list that has been published at least once — an unpublished list returns list_not_published.
  • The publishable key issued for the application that will call this endpoint.
  • The runtime base URL for the environment you are targeting — the AutoSugges dashboard's integration panel shows it.

Parameters

Every parameter this endpoint accepts, whether it is required, and where a caller gets its value
ParameterPlaceholderWhere it comes from
baseUrlRequired · public by designYOUR_RUNTIME_BASE_URLThe AutoSugges dashboard's integration panel, for the environment you are deploying to. The origin of the AutoSugges runtime Worker — scheme and host, no trailing slash and no path. The SDK appends /v1/... itself.
publishableKeyRequired · public by designYOUR_PUBLISHABLE_KEYThe AutoSugges dashboard, under the application that will make the queries. Identifies the consumer, the application, the subscription, the canonical list and the query policy in a single server-side lookup. The client never supplies a list id, tenant id or version hash — if a generated integration is passing one of those, it is wrong.
accessTokenOptional · never in client codeYOUR_SERVER_MINTED_ACCESS_TOKENYour own backend, which mints it from your AutoSugges credentials. Only for a list whose policy requires a token. Short-lived, sent as authorization: Bearer <token>, and never minted, stored or hardcoded in client code.
qRequired · public by design<text the user typed>The user’s input, normalized (trimmed, lower-cased) before you send it. Below the list's minQueryChars (from bootstrap) the server returns query_too_short at HTTP 200 with no items and does not bill it — do not issue the request at all until the input reaches that length. Above 255 characters it returns query_too_long at HTTP 400.
localeOptional · public by design<BCP-47 tag, e.g. en-US>The list's localePolicy.supportedLocales, from bootstrap. Optional. An unsupported locale is not an error — the server falls back to the list's default locale and serves that instead.

How to call it

  1. Bootstrap first. Call GET /v1/bootstrap once per session to learn the real minQueryChars and debounceMs — never hardcode either (DEC-LIST-002/003).
  2. Debounce client-side. Wait debounceMs after the last keystroke, and only once the input is at least minQueryChars, before calling /v1/query.
  3. Send the key as a query parameter. GET /v1/query?key=<publishable key>&q=<text>&locale=<optional>. The key is never a header.
  4. Read the response. items is the pre-ranked suggestion array (at most ~10 per compiled bucket). Render displayValue; store value. ancestors, when present, is the hierarchy chain root-first.
  5. Handle every error by code. A non-2xx status, and the 200-status quota_exceeded/query_too_short conditions, all carry a typed code field. Switch on it — never on the message text, which is deliberately generic.

Example

curl -sS \
  --get 'YOUR_RUNTIME_BASE_URL/v1/query' \
  --data-urlencode "key=YOUR_PUBLISHABLE_KEY" \
  --data-urlencode "q=par" \
  -H "x-request-id: $(uuidgen)"

Security

  • The publishable key travels as a query parameter, never as an Authorization header — that header is reserved for the optional access token of a protected list.
  • A publishable key is public by design. It is safe to embed in client code, a mobile bundle or a server-side script committed to a public repository.

Check that it works

  1. Call with q shorter than minQueryChars and confirm a 200 with code "query_too_short" and an empty (or absent) items array — not an error status.
  2. Call with a valid query and confirm exactly one request is needed per settled input — no per-keystroke traffic.
  3. Call twice with the identical key, query, locale and list version and confirm the response is byte-identical (cache-key dimensions: owner, list, version, locale, full normalized query).
  4. Call with a wrong key and confirm HTTP 401 with code "invalid_key".
  5. Call from an origin not on the key’s allow-list (send an Origin header) and confirm HTTP 403 with code "origin_not_allowed".

A 200 response whose items array holds the pre-ranked suggestions for the query, each with a stable itemId, a value to store and a displayValue to render, served from the edge with no PostgreSQL in the path (DEC-EDGE-001).

Errors this endpoint is likely to return

  • invalid_key
  • origin_not_allowed
  • query_too_short
  • query_too_long
  • quota_exceeded
  • list_not_published
  • artifact_unavailable

The complete error vocabulary

Notes

  • A query longer than the deepest compiled prefix is still served correctly: the server filters the deepest compiled bucket against your full query in memory rather than adding a second read (DEC-MANIFEST-004).
  • An item can match through an alias/synonym compiled at publish time, not only through its own label (DEC-ALIAS-001) — do not assume every returned item’s displayValue literally contains what was typed.