Update Settings

import json
import requests
import uuid
BASE_URL = "https://acme.captain.dev"
API_KEY = "your_write_key"
INDEX = "products"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
}
response = requests.patch(
    f"{BASE_URL}/v1/indexes/{INDEX}/settings",
    headers=headers,
    json={
        "fields": {"material": {"type": "keyword", "facet": True}},
    },
    timeout=30.0,
)
print(json.dumps(response.json(), indent=2))

{
  "object_search": true,
  "settings": {
    "fields": {
      "brand": {
        "type": "keyword",
        "facet": true
      },
      "material": {
        "type": "keyword",
        "facet": true
      }
    }
  },
  "warnings": [],
  "applies_at": "when job job_20261002193012_9f8e7d succeeds",
  "job": {
    "id": "job_20261002193012_9f8e7d",
    "type": "index.build",
    "index": "products",
    "status": "queued"
  }
}

Change some settings, as a JSON merge patch. The reply’s job is the rebuild that applies them; search serves the old settings until it succeeds. acl, tenant_field and audit are set with Captain (403).

Authentication

AuthorizationBearer

A write key, issued by Captain. Server side only. Sent as Authorization: Bearer <key>.

Path parameters

indexstringRequiredformat: "^[a-z0-9][a-z0-9_-]{0,47}$"

index name

Query parameters

rebuildenumOptionalDefaults to false

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)

Allowed values:

Request

a JSON merge patch (RFC 7386) of the settings: objects merge key by key, null removes a key, anything else replaces

Response headers

X-Captain-Applied-Seqinteger

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

X-Captain-Index-IncarnationstringOptional

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

saved

object_searchbooleanOptional

settingsobjectOptional

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.

effectiveobject or nullOptional

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

servedobject or nullOptional

the field table of the build being served

warningslist of objectsOptional

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

applies_atstringOptional

when the settings take effect: served, the next build, when job <id> succeeds, or the build after a running job

jobobject or nullOptional

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

Errors

422

Unprocessable Entity Error