Search Records
Search an index. Keyword and meaning-based matching run together, then filters, facets and sort apply.
Authentication
A search key, issued by Captain. Sent as Authorization: Bearer <key>.
A scoped key for one end user, minted from an issuer key that Captain issues. Sent as Authorization: Bearer <key>.
Path parameters
Request
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
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. On an Object Search index 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
full mode: exact facet counts over the relevance-cut result set
the facets to count, by field name (as the answer names them). On an Object Search index a date facet, or a number facet with more than 1,000 distinct values, has no value counts and is refused (400); capabilities.fields.facet_counts lists the ones that count
instant mode: the id shown first at the previous keystroke (hold-top rule)
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 the meaning (dense) lanes are unchanged: they retrieve, they don't rewrite the query. query_understanding.as_typed says it applied
Object Search: 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). See /llms.txt
soft constraints: reorder, never remove
strict: quantities parsed from the query (under 5 lb) must hold on the record's typed fields; soft: they only rank
a sortable field; search sorts the relevant set (the top 1,000 relevant records)
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
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
search: hits per page (default k)
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
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
per hit _explain: each lane's rank, scores, identifier match, matched words per field
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%)
per hit fields: the typed values (dates as ISO 8601). Access lists are never returned
Response headers
the last update seq search had applied when this request started; the answer reflects at least that much (GET .../updates applied_seq). Not on 401 or 403, nor for an index this server does not have
the index's incarnation, an opaque string: it changes only when the index is deleted and created again (whose seqs start again at 1), or restored from a backup (whose seqs continue from the backup's). Sent with X-Captain-Applied-Seq
Response
matching records (with group_by too: records, not groups)
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
what the engine understood. Keys appear only when they apply; keys not listed here are diagnostics and may change
constraints: strict: hits removed because a parsed quantity failed. hits [] with this > 0 means nothing meets the query's quantities
search with sort: which field and over what set
search with page or per_page