GET /v1/bootstrap — session policy and version resolution
Resolve a publishable key to its list identity, active version hash and effective query policy in one call, before the first query.
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, DEC-LIST-003) 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
| Parameter | Placeholder | Where it comes from |
|---|---|---|
| baseUrlRequired · public 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 Worker — scheme and host, no trailing slash and no path. The SDK appends /v1/... itself. |
| publishableKeyRequired · public 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. |
| accessTokenOptional · never 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
- Call it once per session. GET /v1/bootstrap?key=<publishable key>, at startup, before the first /v1/query call.
- 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.
- 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.
- 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
- Call with a valid key and confirm the response carries list.id, activeVersionHash, and a queryPolicy object with minQueryChars and debounceMs.
- Call with a wrong key and confirm HTTP 401 with code "invalid_key".
- Call against a list that has never been published and confirm code "list_not_published".
- Confirm this call costs no query-quota: bootstrap never meters and never reads a compiled bucket.
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_keyorigin_not_allowedlist_not_published
Notes
- Bootstrap never returns list items or a version’s compiled data — only policy and identifiers. It costs one KV read, with no meter, cache or bucket lookup behind it.