Replace Settings
Replace the whole settings object. The reply’s job is the rebuild that applies it. acl, tenant_field and audit must stay as they are (403).
Authentication
A write key, issued by Captain. Server side only. Sent as Authorization: Bearer <key>.
Path parameters
Headers
Replays within 24 hours return the stored response (header Idempotent-Replayed: true). The same key on a different request answers 422. A concurrent duplicate answers 409. Failed requests do not keep the key.
Query parameters
Off unless Captain turns it on for your tenant, and ignored until then. true: accept a change that only a full build applies; the change is saved and the build starts (202 with the job)
Request
exactly these text fields are searched; the first is primary
exact codes: ranked first on an exact match, exact filters
record-level access control, enforced in the engine on every result, count and facet, and on spelling help (it learns only from what the key may see). Keys must carry principals; the admin key sees all
a keyword field every non-admin key must be restricted to
true: an upload rejects a record whose value doesn’t fit its field’s declared type (date, number, bool, enum, geo), by NDJSON line or array index (code BAD_VALUE; on_error=skip stages the rest). false (default): the upload takes it, and the build leaves that value empty (the record stays searchable by its text) and counts it in a BAD_VALUES warning; a field whose type the settings declare and where more than half the values don’t fit fails the build with error_code BAD_VALUES (an inferred type in that case is read as text instead: TYPE_FALLBACK warning)
exact search and stable tie-breaking: the same query and filters give the same ids, order and total (scores equal to within 1e-5) while the index receives no writes, across restarts and concurrent load. Not promised across rebuilds or after records are added, changed or deleted. Unset: on for an index built with fewer than 100,000 records, off at 100,000 or more; true or false always wins
the index’s default grouping for every search (Algolia’s distinct). A request’s group_by overrides it; group_by: false turns it off for one request
what the index holds, for interfaces (a label only)
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
Typed fields inferred from the records, with explicit overrides. Knobs, not tuning: ranking uses the one general config for every index. Applies at the next build.
every field with its inferred or set type and flags (plus up to 3 example values under samples; never for the access-list fields), and children. Identifier fields carry format (cusip, isin, lei, cik, docket, citation, icd10) when 80% of values share one
settings that were resolved by a rule rather than by you. FACET_NO_COUNTS: a facet with more than 1,000 distinct values, or a date facet, has no value counts (it still filters, sorts and gives facet_stats min and max). Otherwise: several fields claiming a single-valued role (title, brand, category, section), with the one that won; ID_FROM_CODE_FIELD: no id field was given and the build keys on the code field named. UNKNOWN_FIELD: settings.fields names a field no record added so far has, so it does nothing yet. FACET_ON_TEXT: a facet on a text field, with the share of its values that differ; type it keyword if its values are short labels. ID_INFERRED (schema preview): the id was detected from the data, please confirm it. SETTING_NO_EFFECT: weight or role set on a built-in field name (title, description, brand, category and the other built-in names), which keeps its built-in role, so the setting does nothing. None blocks
when the settings take effect: served, the next build, when job <id> succeeds, or the build after a running job
Update Settings and Replace Settings, answered 202: the rebuild that applies the change, or the build already running, after which the next build applies it