GET /v1/bootstrap — session policy and version resolution

What does the AutoSugges bootstrap endpoint return?

GET /v1/bootstrap resolves a publishable key to its list identity, the active version hash and the effective query policy, including minQueryChars and debounceMs. Call it once per session before the first query. It returns no items and is never counted against your query quota.

What this endpoint does

A correct raw HTTP call to GET /v1/bootstrap, used to read the real minQueryChars/debounceMs a list is configured with (never hardcoded) and the active version hash a client can compare to detect staleness.

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

• baseUrl

  Requiredpublic by design

  YOUR_RUNTIME_BASE_URL
  The AutoSugges dashboard's integration panel, for the environment you are deploying to. The origin of the AutoSugges runtime — scheme and host, no trailing slash and no path. The SDK appends /v1/... itself.
• publishableKey

  Requiredpublic by design

  YOUR_PUBLISHABLE_KEY
  The 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.
• accessToken

  Optionalnever in client code

  YOUR_SERVER_MINTED_ACCESS_TOKEN
  Your 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.

How to call it

1. Call it once per session. GET /v1/bootstrap?key=<publishable key>, at startup, before the first /v1/query call.
2. Store the policy, not a guess. Read queryPolicy.minQueryChars and queryPolicy.debounceMs from the response and use them as the literal thresholds for every subsequent query on this list.
3. Keep the version hash. activeVersionHash identifies the currently serving published version. Compare it on a later bootstrap call to detect that the list has republished.
4. Handle every error by code. The same typed error vocabulary /v1/query returns — switch on code, never on message text.

Example

curl -sS \
  --get 'YOUR_RUNTIME_BASE_URL/v1/bootstrap' \
  --data-urlencode "key=YOUR_PUBLISHABLE_KEY"

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 a valid key and confirm the response carries list.id, activeVersionHash, and a queryPolicy object with minQueryChars and debounceMs.
2. Call with a wrong key and confirm HTTP 401 with code "invalid_key".
3. Call against a list that has never been published and confirm code "list_not_published".
4. Confirm this call costs no query quota: bootstrap is never counted against it.

A 200 response naming the resolved list, its active version hash, and the effective query and locale policy this key currently serves — the only source of truth for minQueryChars and debounceMs a client should ever use.

Errors this endpoint is likely to return

• invalid_key
• origin_not_allowed
• list_not_published

The complete error vocabulary

Notes

• Bootstrap never returns list items — only policy and identifiers.