> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Search As You Type

POST https://acme.captain.dev/v1/indexes/{index}/typeahead
Content-Type: application/json

Search with the text typed so far, once per keystroke. Fixes spelling and completes the last word. Same response shape as Search Records.

Reference: https://docs.captain.dev/reference/product-search/searches/search-as-you-type

## Authentication

- `Authorization` header (bearer token, required) — A search key, issued by Captain. Sent as Authorization: Bearer \<key>.
- `Authorization` header (bearer token, required) — A scoped key for one end user, minted from an issuer key that Captain issues. Sent as Authorization: Bearer \<key>.

## Request

### Path parameters

- `index` (string, required) — index name

### Body (application/json)

This endpoint expects a SearchRequest.

- `query` (string, optional)
- `k` (integer, optional, default: 10) — results to return, up to 1,000. The first 100 are the full ranking; 101-1,000 continue it (the rest of the blended ranking, then keyword order), the same list for every page of a query. sort, a geo sort and strict order or filter the top 1,000 relevant records; prefer re-orders the top 100 and leaves 101-1,000 in rank order; with group_by, k counts groups, formed from the top 1,000
- `filters` (map from string to any, optional) — field -> value (exact), or list (any of). Also price\_min, price\_max, rating\_min, t\_\<field>*min / t*\<field>\_max for typed numbers (flexible schema), attributes.\<key> for attribute values. A filterable field is named as the settings name it: a value or a list of values, or, on a number or date field, a range \{gte, gt, lte, lt}. A bare date as lte covers that whole day (lte 2003-12-31 keeps filings made on the 31st). The filter expression (filter) says the same and more
- `rule_contexts` (list of string, optional) — rule contexts (Algolia ruleContexts): a rule whose condition has a context fires only when the search sends it
- `facets` (boolean, optional, default: true) — Search Records counts facets unless this is false. The counts cover the most relevant results, up to 2,000, not every match, so facets_exact is false. Search As You Type counts facets only when this is true or facet_keys names some.
- `facet_keys` (list of string, optional) — the facets to count, by field name (as the answer names them). A date facet, a facet with more than 1,000 distinct values at build, or a field that is not a facet with more than 500, has no value counts and is refused (400); capabilities.fields.facet_counts lists the facets that count
- `facet_limit` (integer, optional)
- `exact_total` (boolean, optional, default: false) — Search Records only. Answer as total the number the Algolia host answers as nbHits for the same query: the hits it can page through while under 1,000 (total_basis pageable), else every record that contains every query word, never below 1,000 (all_matches; at the 1,000 floor total_exact is false, paging_limit). Count the facets in facet_keys over every record that contains every query word. Bounded so a search never waits long: when the count is busy or over its time budget, total stays the candidate count and total_basis says why. Off by default: on a large index a common word makes the count cost more than the search
- `prev_top` (string, optional) — Search As You Type only: the id of the hit you showed first after the previous keystroke. If that record is now second or third, it moves back to first and the rest keep their order, so the top suggestion doesn't jump while the shopper types.
- `as_typed` (boolean, optional, default: false) — search exactly what was typed ("Search instead for walnutt"): no spelling correction, no word split or join, no glued codes, no synonym expansion. Identifier matching, filters and meaning-based matching are unchanged: they find records, they don't rewrite the query. query_understanding.as_typed says it applied
- `user_token` (string, optional) — who searched, for analytics
- `analytics` (boolean, optional, default: true) — false: this search is not logged for analytics (no search log row, no query_id, so it never counts in search counts, the no-result rate or a test's readout); for your own previews, evals and relevance checks. Any key. An A/B assignment still routes it. The answer carries analytics: false. Default true
- `filter` (string, optional) — a filter expression (strict), e.g. status IN ["open", "pending"] AND filed_at >= 2024-01-01 AND office WITHIN 25 km OF (40.71, -74.00). The Search guide's Filters section lists the syntax
- `prefer` (list of Prefer, optional) — soft constraints: reorder, never remove
- `constraints` (enum, optional, default: soft) — strict: quantities parsed from the query (under 5 lb) must hold on the record's typed fields; soft: they only rank
  - Allowed values: `soft`, `strict`
- `sort` (list of SearchRequestSortItems, optional) — a sortable field; search sorts the relevant set (the top 1,000 relevant records)
- `group_by` (SearchRequestGroupBy, optional) — one hit per value of a field (product variants: Algolia's distinct), with up to size - 1 more members: today's ranking, deduplicated. k counts groups. Search only. false: no grouping, whatever the index's default
- `page` (integer, optional) — search: which page, from 0, of per_page hits. Pages cut the final ranking (after filter, prefer, strict, sort and group_by) within the top 1,000 relevant records, the same list on every page; a page past that is 400 PAGE_TOO_DEEP. To walk every match, browse with a filter, sort, k and page
- `per_page` (integer, optional) — search: hits per page (default k)
- `facet_query` (SearchRequestFacetQuery, optional) — search inside one facet's values (Algolia searchForFacetValues): the values whose text, or any of whose words, starts with prefix (case and accents folded), with their counts over the same set as facets
- `facet_stats` (boolean, optional) — min and max of each number and date facet (Algolia facets_stats; no average: it would need every match's value). Search: over the relevance set, up to 1,000 distinct values, and exhaustive says whether that covered every one. Browse: exact over every record the filter matches and the key may see
- `explain` (boolean, optional) — per hit _explain: its rank and score in keyword and in meaning-based matching, identifier match, matched words per field
- `highlight` (SearchRequestHighlight, optional)
- `citations` (SearchRequestCitations, optional) — per hit _citations: the best passages (and child records) with character offsets. Best effort, not a guarantee: on CUAD contracts (CUAD dev, 469 queries, os-generalize's labels as of 2026-09-27 10:36Z), when the right contract ranks first, one of its 3 cited passages holds the annotated clause 64.6% of the time (the first citation 45.7%)
- `fields` (SearchRequestFields, optional) — per hit fields: the typed values (dates as ISO 8601). Access lists are never returned

## Response

### 200

results

- `hits` (list of Hit, optional)
- `total` (integer, optional) — search: the number of candidates the search ranked (an estimate, not a count of every match) unless the search asked exact_total, when it is the number the Algolia host answers as nbHits (see total_basis). Page with page.has_more, not total. Browse: every record the filter keeps. With group_by too: records, not groups
- `total_exact` (boolean, optional) — true when total is an exact number (search with exact_total: total_basis pageable or all_matches). False: an estimate (candidates) or the 1,000 floor (paging_limit)
- `total_basis` (enum, optional) — what total is: pageable (exact: the hits the search can page through, under 1,000), all_matches (exact: every record that contains every query word, 1,000 or more), paging_limit (1,000, a floor: more may match), candidates (exact_total not asked, or type-ahead), or why an asked-for exact count fell back: busy, time_budget, error, no_required_words (no query word is required, so every record would match)
  - Allowed values: `pageable`, `all_matches`, `paging_limit`, `candidates`, `busy`, `time_budget`, `error`, `no_required_words`
- `facet_detail` (map from string to SearchResponseFacetDetail, optional) — per facet in facets: basis all_matches (counted over every match, exact true) or relevant_results (counted over the relevance-cut set, exact false, with the reason when an asked-for exact count fell back)
- `grouped` (SearchResponseGrouped, optional) — present when results are grouped: the ranking, collapsed by the field's value. A grouped search reads the 100 most relevant records, and further down the top 1,000 when k x size x 4 needs more; depth says how many it read
- `facets` (map from string to list of SearchResponseFacetsItems, optional)
- `facets_exact` (boolean, optional) — true only when every facet was counted over every matching record (browse). Search counts facets over the relevance-cut set (the most relevant results, up to 2,000): false
- `facet_set_size` (integer, optional)
- `query_id` (string, optional)
- `assignment` (AssignmentDecision, optional) — only on a search of a catalog with an assignment that sent a user_token: the shopper's group, and the index that served it
- `analytics` (boolean, optional) — false when the request sent analytics: false (not logged, no query_id); absent otherwise
- `query_understanding` (QueryUnderstanding, optional) — what the engine understood. Keys appear only when they apply; keys not listed here are diagnostics and may change
- `user_data` (list of SearchResponseUserDataItems, optional) — the userData of each rule applied to this search, in rule order (at most 10). Absent when no applied rule has any
- `facet_ordering` (FacetOrdering, optional) — how a page orders facets and their values (Algolia renderingContent.facetOrdering, snake_case). Returned on search and browse when the index or an applied rule sets one; the client orders with it
- `redirect` (SearchResponseRedirect, optional) — an applied rule's redirect (the first in rule order): the page to send the shopper to instead of showing these results. Absent when no applied rule redirects
- `constraints_removed` (integer, optional) — constraints: strict: hits removed because a parsed quantity failed. hits [] with this > 0 means nothing meets the query's quantities
- `sort` (SearchResponseSort, optional) — search with sort: which field and over what set
- `page` (SearchResponsePage, optional) — search with page or per_page
- `facet_query` (SearchResponseFacetQuery, optional)
- `facet_stats` (map from string to SearchResponseFacetStats, optional)
- `request` (SearchResponseRequest, optional) — What ran. mode is full for Search Records and instant for Search As You Type, which skips the slower ranking steps to answer each keystroke. build is the index build that answered.
- `timing` (SearchResponseTiming, optional)

## Types

### Prefer

- `filter` (string, required) — a filter expression
- `weight` (double, optional, default: 0.5) — added to matching results' scores in units of this query's score spread; negative demotes

### SearchRequestSortItems

- `field` (string, optional)
- `order` (enum, optional)
  - Allowed values: `asc`, `desc`
- `near` (SearchRequestSortItemsNear, optional) — on a geo field: the point to measure from. asc puts the nearest records first

### SearchRequestGroupBy

one hit per value of a field (product variants: Algolia's distinct), with up to size - 1 more members: today's ranking, deduplicated. k counts groups. Search only. false: no grouping, whatever the index's default

### SearchRequestFacetQuery

search inside one facet's values (Algolia searchForFacetValues): the values whose text, or any of whose words, starts with prefix (case and accents folded), with their counts over the same set as facets

- `field` (string, required)
- `prefix` (string, optional)
- `limit` (integer, optional, default: 10)

### SearchRequestHighlight

### SearchRequestCitations

per hit _citations: the best passages (and child records) with character offsets. Best effort, not a guarantee: on CUAD contracts (CUAD dev, 469 queries, os-generalize's labels as of 2026-09-27 10:36Z), when the right contract ranks first, one of its 3 cited passages holds the annotated clause 64.6% of the time (the first citation 45.7%)

### SearchRequestFields

per hit fields: the typed values (dates as ISO 8601). Access lists are never returned

### Hit

a hit is its record: the id, every field of the record as it was sent (url and text fields included; access lists never), and score. title, brand, category, price, rating and image_url appear when the record has a value for them (a product card's fields, under those names even when the record names them otherwise); description is the record's own description field. fields, _explain, _highlight, _citations, group and identifier_match come when asked for. An index last built by an older engine answers in the product shape until its next build

- `group` (HitGroup, optional) — group_by: this hit is its group's best-ranked record; hits are up to size - 1 more members, in rank order (value null: the record has none, a group of its own)
- `id` (string, optional)
- `title` (string, optional, nullable)
- `brand` (string, optional, nullable)
- `category` (string, optional, nullable)
- `price` (double, optional, nullable)
- `rating` (double, optional, nullable)
- `image_url` (string, optional, nullable)
- `description` (string, optional)
- `score` (double, optional) — the relevance score, from keyword and meaning-based matching together. Optional: on an access-controlled index, results for keys other than admin come without scores, because scores depend on the whole catalog, including records the caller cannot see. The order of hits is the ranking either way
- `fields` (HitFields, optional) — with fields: typed values
- `identifier_match` (HitIdentifierMatch, optional) — this hit's identifier field holds, whole, a code the query typed ("matched cusip 66537J812"). Absent when there is no such match
- `_explain` (HitExplain, optional)
- `_highlight` (map from string to string, optional)
- `_citations` (list of HitCitationsItems, optional)
- `geo_distance_m` (double, optional) — with a geo sort: meters from the sort's near point. Absent when the record has no location

### SearchResponseFacetDetail

- `basis` (enum, optional)
  - Allowed values: `all_matches`, `relevant_results`
- `exact` (boolean, optional)
- `reason` (string, optional)

### SearchResponseGrouped

present when results are grouped: the ranking, collapsed by the field's value. A grouped search reads the 100 most relevant records, and further down the top 1,000 when k x size x 4 needs more; depth says how many it read

- `field` (string, optional)
- `size` (integer, optional)
- `depth` (integer, optional) — ranked candidates collapsed
- `complete` (boolean, optional) — false: more records matched than the depth, so a group (or a member) ranked below it is not shown
- `groups` (integer, optional) — groups among all matches. Present only when complete is true; absent when complete is false, because the count is then unknown

### SearchResponseFacetsItems

- `value` (any, optional)
- `count` (integer, optional)

### AssignmentDecision

only on a search of a catalog with an assignment that sent a user_token: the shopper's group, and the index that served it

- `layer` (string, required)
- `group` (string, required)
- `index` (string, required) — the copy that served the search, or the catalog itself
- `fallback` (boolean, required) — true: the group's copy could not answer here (missing, not built, loading), so the catalog served

### QueryUnderstanding

what the engine understood. Keys appear only when they apply; keys not listed here are diagnostics and may change

- `corrections` (list of list of string, optional) — [[typed, fixed]]
- `splitjoin` (list of list of string, optional) — [[typed, fixed]] word splits and joins
- `as_typed` (boolean, optional) — the request asked for as_typed: nothing above rewrote the query
- `reduced` (boolean, optional) — present (true) only when this answer ran with reduced features: spelling fixes, completions, suggestions and zero-result answers may be off, so treat a missing correction as not checked. Results are still filtered to the caller as always. It names no cause. Absent otherwise, never false
- `price_filter` (QueryUnderstandingPriceFilter, optional) — a price phrase in the query, applied as a filter
- `constraints` (list of list of any, optional) — [[quantity, value in the quantity's base unit, op]], e.g. ["weight", 6.61, "le"]
- `completions` (list of string, optional) — typeahead
- `partial` (string, optional) — typeahead: the word still being typed
- `identifiers` (list of string, optional) — query tokens treated as codes
- `identifier_tier` (integer, optional) — how many leading hits matched an identifier exactly
- `held_top` (boolean, optional)
- `evidence` (integer, optional)
- `evidence_missing` (integer, optional)
- `missing_words` (list of string, optional) — typed words no record carries
- `no_results` (string, optional) — present only when zero hits is the intended answer: the reason
- `relaxed` (QueryUnderstandingRelaxed, optional) — answered without some typed words: 'No match for \<dropped>. Showing results for \<query>' (empty query = related records). Filters are never relaxed
- `relaxed_reason` (string, optional)
- `category_match` (list of string, optional)
- `synonyms` (list of string, optional)
- `rules` (list of string, optional)

### SearchResponseUserDataItems

### FacetOrdering

how a page orders facets and their values (Algolia renderingContent.facetOrdering, snake_case). Returned on search and browse when the index or an applied rule sets one; the client orders with it

- `facets` (FacetOrderingFacets, optional)
- `values` (map from string to FacetOrderingValues, optional)

### SearchResponseRedirect

an applied rule's redirect (the first in rule order): the page to send the shopper to instead of showing these results. Absent when no applied rule redirects

- `url` (string, optional)
- `rule` (string, optional) — the rule's objectID

### SearchResponseSort

search with sort: which field and over what set

### SearchResponsePage

search with page or per_page

- `number` (integer, optional)
- `per_page` (integer, optional)
- `has_more` (boolean, optional) — another page exists within the depth
- `depth` (integer, optional) — how deep search pages reach (1,000 relevant records)

### SearchResponseFacetQuery

- `field` (string, optional)
- `prefix` (string, optional)
- `values` (list of SearchResponseFacetQueryValuesItems, optional)
- `exhaustive` (boolean, optional)

### SearchResponseFacetStats

### SearchResponseRequest

What ran. mode is full for Search Records and instant for Search As You Type, which skips the slower ranking steps to answer each keystroke. build is the index build that answered.

### SearchResponseTiming

- `engine_ms` (double, optional)
- `stages` (SearchResponseTimingStages, optional)

### SearchRequestSortItemsNear

on a geo field: the point to measure from. asc puts the nearest records first

- `lat` (double, required)
- `lng` (double, required)

### GroupBy

- `field` (string, required) — a single-valued keyword, identifier or enum field. A record without a value is a group of its own
- `size` (integer, optional, default: 1) — hits per group: 1 is Algolia's distinct: true, N is distinct: N

### SearchRequestHighlight1

- `fields` (list of string, optional)
- `pre_tag` (string, optional)
- `post_tag` (string, optional)

### SearchRequestCitations1

- `n` (integer, optional)
- `size` (integer, optional)

### HitGroup

group_by: this hit is its group's best-ranked record; hits are up to size - 1 more members, in rank order (value null: the record has none, a group of its own)

- `field` (string, optional)
- `value` (any, optional)
- `hits` (list of HitGroupHitsItems, optional)

### HitFields

with fields: typed values

### HitIdentifierMatch

this hit's identifier field holds, whole, a code the query typed ("matched cusip 66537J812"). Absent when there is no such match

- `field` (string, optional)
- `value` (string, optional)

### HitExplain

- `lanes` (map from string to integer, optional)
- `fused_score` (double, optional) — optional: withheld with score
- `final_score` (double, optional) — optional: withheld with score
- `identifier_match` (boolean, optional)
- `matched` (map from string to list of string, optional)
- `preferred` (double, optional)

### HitCitationsItems

- `field` (string, optional)
- `child` (HitCitationsItemsChild, optional)
- `start` (integer, optional)
- `end` (integer, optional)
- `text` (string, optional)
- `highlighted` (string, optional)
- `matched` (list of string, optional)
- `score` (double, optional)

### QueryUnderstandingPriceFilter

a price phrase in the query, applied as a filter

- `price_min` (double, optional)
- `price_max` (double, optional)

### QueryUnderstandingRelaxed

answered without some typed words: 'No match for \<dropped>. Showing results for \<query>' (empty query = related records). Filters are never relaxed

- `dropped` (list of string, optional)
- `query` (string, optional)

### FacetOrderingFacets

- `order` (list of string, optional)

### FacetOrderingValues

- `order` (list of string, optional) — values pinned first, in this order
- `sort_remaining_by` (enum, optional, default: count)
  - Allowed values: `count`, `alpha`, `hidden`
- `hide` (list of string, optional)

### SearchResponseFacetQueryValuesItems

### SearchResponseTimingStages

### HitGroupHitsItems

### HitCitationsItemsChild

- `index` (integer, optional)
- `id` (string, optional)
- `title` (string, optional)

## Examples

**Request**

```json
{
  "query": "waterpr",
  "k": 3
}
```

**Response**

```json
{
  "hits": [
    {
      "id": "sku-10482",
      "title": "Moab 3 Mid Waterproof Hiking Boot",
      "brand": "Merrell",
      "category": "Hiking Boots",
      "price": 139,
      "rating": 4.6,
      "image_url": "https://cdn.acme.example/img/sku-10482.jpg",
      "score": 1.42
    },
    {
      "id": "sku-11020",
      "title": "Targhee III Waterproof Mid Boot",
      "brand": "KEEN",
      "category": "Hiking Boots",
      "price": 150,
      "rating": 4.4,
      "image_url": "https://cdn.acme.example/img/sku-11020.jpg",
      "score": 1.18
    },
    {
      "id": "sku-10517",
      "title": "X Ultra 4 Mid GTX Hiking Boot",
      "brand": "Salomon",
      "category": "Hiking Boots",
      "price": 165,
      "rating": 4.5,
      "image_url": "https://cdn.acme.example/img/sku-10517.jpg",
      "score": 0.97
    }
  ],
  "total": 57,
  "query_id": "e41b7c9a2d5f4a86b03e7d1c9f2a6b58",
  "query_understanding": {
    "completions": [
      "waterproof",
      "waterproofing"
    ],
    "partial": "waterpr"
  },
  "request": {
    "mode": "instant",
    "build": "b20260928201247"
  },
  "timing": {
    "engine_ms": 8.7
  }
}
```

**SDK Code**

```python Python REST
import json
import requests

BASE_URL = "https://acme.captain.dev"
API_KEY = "your_search_key"
INDEX = "products"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{BASE_URL}/v1/indexes/{INDEX}/typeahead",
    headers=headers,
    json={
        "query": "waterpr",
        "k": 3,
    },
    timeout=30.0,
)

print(json.dumps(response.json(), indent=2))
```

```typescript TypeScript REST
const BASE_URL = "https://acme.captain.dev";
const API_KEY = "your_search_key";
const index = "products";

const response = await fetch(`${BASE_URL}/v1/indexes/${index}/typeahead`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "waterpr",
    k: 3,
  }),
});

const result = await response.json();
console.log(JSON.stringify(result, null, 2));
```