> ## Documentation Index > Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt > Use this file to discover all available pages before exploring further. # Mint an autocomplete session > Mints the grant every request to the autocomplete service carries in ``X-Autocomplete-Session``. Minting writes one Order; the keystrokes it admits write nothing. An organization mints without limit unless one is set for it, ``sessions_per_window`` per ten minutes and ``sessions_per_day`` per rolling day (each ``null`` when there is none), one pool drawn from by every caller in it; past either the mint answers 429. The grant is bound to the ``Origin`` it was minted with, expires after ``expires_in`` seconds (refresh at about 80% of it; ``expires_at`` is the same instant as a UTC timestamp, for display) and admits ``request_budget`` requests per route. A sandbox application's grant is served the sandbox's own index, and its mint writes no Order and counts against neither limit. A caller whose ``autocomplete.enabled`` override is off is answered 403; a locked organization is answered 402. ## OpenAPI ````yaml /api-reference/openapi.json post /autocomplete/sessions openapi: 3.1.0 info: title: baselayer-api-service version: 0.1.0 servers: - url: https://api.baselayer.com/ security: [] paths: /autocomplete/sessions: post: tags: - Autocomplete summary: Mint an autocomplete session description: >- Mints the grant every request to the autocomplete service carries in ``X-Autocomplete-Session``. Minting writes one Order; the keystrokes it admits write nothing. An organization mints without limit unless one is set for it, ``sessions_per_window`` per ten minutes and ``sessions_per_day`` per rolling day (each ``null`` when there is none), one pool drawn from by every caller in it; past either the mint answers 429. The grant is bound to the ``Origin`` it was minted with, expires after ``expires_in`` seconds (refresh at about 80% of it; ``expires_at`` is the same instant as a UTC timestamp, for display) and admits ``request_budget`` requests per route. A sandbox application's grant is served the sandbox's own index, and its mint writes no Order and counts against neither limit. A caller whose ``autocomplete.enabled`` override is off is answered 403; a locked organization is answered 402. operationId: mint_autocomplete_session_autocomplete_sessions_post requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/v1.AutocompleteSessionRequest' - type: 'null' title: Request responses: '201': description: Response content: application/json: schema: $ref: '#/components/schemas/v1.AutocompleteSessionGrantResponse' application/vnd.baselayer.v1+json: schema: $ref: '#/components/schemas/v1.AutocompleteSessionGrantResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: v1.AutocompleteSessionRequest: properties: scope: anyOf: - $ref: '#/components/schemas/AutocompleteSessionScopeRequest' - type: 'null' description: >- Narrows what the session may search, so a leaked session can do no more than this. Left out, everything the caller may search. additionalProperties: false type: object title: AutocompleteSessionRequest (v1) description: What a caller asks of a new session; the body is optional. v1.AutocompleteSessionGrantResponse: description: >- A grant from ``POST /autocomplete/sessions``, and its organization's limits. properties: session_token: description: >- Opaque, signed session grant. Send it verbatim in the ``X-Autocomplete-Session`` header of every autocomplete request; it carries its own expiry and budget. examples: - eyJhbGciOiJFZERTQSIsInR5cCI6ImFjczEiLCJraWQiOiJ… title: Session Token type: string expires_in: description: >- 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. examples: - 120 title: Expires In type: integer expires_at: description: >- When the grant stops working, in UTC: the token's own expiry, for display and logs. Time refreshes from ``expires_in``. examples: - '2026-09-23T12:03:00Z' format: date-time title: Expires At type: string request_budget: description: >- 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. examples: - 10 title: Request Budget type: integer pivot_allowance: description: >- 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. examples: - 5 title: Pivot Allowance type: integer filter_min_stem: description: >- Characters the query needs before the ``person.*``, ``address.*`` and ``state`` filters narrow the suggestions; shorter, a filtered request is a 422 naming ``q``. examples: - 5 title: Filter Min Stem type: integer min_query_chars: anyOf: - type: integer - type: 'null' default: null description: >- 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. examples: - 2 title: Min Query Chars filter_rules: anyOf: - additionalProperties: $ref: '#/components/schemas/v1.AutocompleteFilterRule' propertyNames: $ref: '#/components/schemas/v1.AutocompleteRoute' type: object - type: 'null' default: null description: >- 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. title: Filter Rules scope: $ref: '#/components/schemas/v1.AutocompleteSessionScope' description: >- 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: anyOf: - type: integer - type: 'null' description: >- 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. title: Sessions Per Window sessions_per_day: anyOf: - type: integer - type: 'null' description: >- Sessions this organization may mint in a rolling 24 hours, shared and refused the same way. ``null`` when there is no limit. title: Sessions Per Day user_sessions_per_window: anyOf: - type: integer - type: 'null' description: >- 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. title: User Sessions Per Window user_sessions_per_day: anyOf: - type: integer - type: 'null' description: >- 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. title: User Sessions Per Day required: - session_token - expires_in - expires_at - request_budget - pivot_allowance - filter_min_stem - scope - sessions_per_window - sessions_per_day - user_sessions_per_window - user_sessions_per_day title: AutocompleteSessionGrantResponse (v1) type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AutocompleteSessionScopeRequest: properties: routes: anyOf: - additionalProperties: items: $ref: '#/components/schemas/AutocompleteRelation' type: array propertyNames: $ref: '#/components/schemas/AutocompleteRoute' type: object - type: 'null' minLength: 1 title: Routes description: >- The routes the session may query and, per route, the relations a request may include or filter by. Each must be one the caller may reach (else 403) and a relation of its route (else 422); none at all is a 422, since that session could query nothing. Left out, every route the caller may query, with every relation. examples: - businesses: - addresses max_limit: anyOf: - type: integer maximum: 20 minimum: 1 - type: 'null' title: Max Limit description: The most suggestions a request may ask for. Left out, 20. examples: - 5 additionalProperties: false type: object title: AutocompleteSessionScopeRequest description: |- A narrowing of what a session may search; either part left out narrows nothing on that side. v1.AutocompleteFilterRule: additionalProperties: false description: What one route holds its narrowing filters to. properties: min_stem: description: >- Characters the query needs, counted as ``count`` says, before any filter in ``gated`` narrows the suggestions. examples: - 5 title: Min Stem type: integer count: description: >- How the query's characters are counted: ``stem`` (letters and digits, a symbol such as ``&`` counting as the word it stands for) or ``person_name`` (the spelling the people index uses, ASCII letters only). Another value may follow; one a client does not know is no reason to stop it counting its own way. examples: - stem title: Count type: string gated: description: >- The request parameters that wait for ``min_stem``: a request carrying one of them with a shorter query is a 422 naming ``q``, unless ``short_allowed_with`` applies. examples: - - person.name - state items: type: string title: Gated type: array short_allowed_with: description: >- The parameters that let a non-empty query shorter than ``min_stem`` through. A necessary condition, not a promise: a request that carries one still runs only if the search can answer it, and may be refused. examples: - - business.name items: type: string title: Short Allowed With type: array required: - min_stem - count - gated - short_allowed_with title: AutocompleteFilterRule type: object v1.AutocompleteSessionScope: additionalProperties: false description: >- What a session may search: the routes it may query and, per route, the relations a request may include or filter by, and the most rows a request may ask for. properties: routes: additionalProperties: items: $ref: '#/components/schemas/v1.AutocompleteRelation' type: array description: >- Each route the session may query, and the relations a request on it may include or filter by. Any other route answers 403, and so does a relation outside the list. examples: - businesses: - addresses - people propertyNames: $ref: '#/components/schemas/v1.AutocompleteRoute' title: Routes type: object max_limit: description: >- The most suggestions a request may ask for; a larger ``limit`` answers 422. examples: - 20 maximum: 20 minimum: 1 title: Max Limit type: integer required: - routes - max_limit title: AutocompleteSessionScope type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError AutocompleteRelation: description: >- A kind of row a suggestion relates to: the key of ``related.``. enum: - businesses - people - addresses title: AutocompleteRelation type: string v1.AutocompleteRelation: description: >- A kind of row a suggestion relates to: the key of ``related.``. enum: - businesses - people - addresses title: AutocompleteRelation type: string securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.