Skip to main content
POST
Mint an autocomplete session

Authorizations

X-API-Key
string
header
required

Body

application/json

What a caller asks of a new session; the body is optional.

scope
AutocompleteSessionScopeRequest · object | null

Narrows what the session may search, so a leaked session can do no more than this. Left out, everything the caller may search.

Response

Response

A grant from POST /autocomplete/sessions, and its organization's limits.

session_token
string
required

Opaque, signed session grant. Send it verbatim in the X-Autocomplete-Session header of every autocomplete request; it carries its own expiry and budget.

Example:

"eyJhbGciOiJFZERTQSIsInR5cCI6ImFjczEiLCJraWQiOiJ…"

expires_in
integer
required

Seconds until the grant expires, counted from this response. Time the refresh from this, not from expires_at: it is right however far the caller's clock is off. Mint the next grant at about 80% of it so expiry never lands on the typing path.

Example:

120

expires_at
string<date-time>
required

When the grant stops working, in UTC: the token's own expiry, for display and logs. Time refreshes from expires_in.

Example:

"2026-09-23T12:03:00Z"

request_budget
integer
required

Requests this session may make per autocomplete route. Past it the autocomplete service answers 429 with session_budget_spent; the remedy is a new session, not a retry.

Example:

10

pivot_allowance
integer
required

How many times this session may change its query to a different name before the autocomplete service refuses it (429, code 482). Growing, trimming or correcting the name being typed never counts.

Example:

5

filter_min_stem
integer
required

Characters the query needs before the person.*, address.* and state filters narrow the suggestions; shorter, a filtered request is a 422 naming q.

Example:

5

scope
AutocompleteSessionScope · object
required

What this session may search: the routes, the relations per route, and the most suggestions a request may ask for. Offer a search only where its route is listed.

sessions_per_window
integer | null
required

Sessions this organization may mint per ten-minute window, one number shared by every user and API key in it; the mint past it is answered 429 with a Retry-After. null when there is no limit.

sessions_per_day
integer | null
required

Sessions this organization may mint in a rolling 24 hours, shared and refused the same way. null when there is no limit.

user_sessions_per_window
integer | null
required

Sessions a user signed in to the console may mint per ten-minute window, their own pool beside the organization's; past it the mint answers 429 with a Retry-After. null for an API key, whose sessions are billed, or when there is no limit.

user_sessions_per_day
integer | null
required

Sessions a user signed in to the console may mint in a rolling 24 hours, refused the same way. null for an API key, or when there is no limit.

min_query_chars
integer | null

Characters a query needs before the autocomplete service searches at all; shorter, a request is a 422 naming q. Advisory: the service holds it on its own.

Example:

2

filter_rules
Filter Rules · object | null

What each route in scope holds its narrowing filters to, so a client can wait before sending a filter the service would refuse. Each route's min_stem is what this session enforces on it, and filter_min_stem is the strictest of them. The service decides; a client that ignores this learns the same from the 422.