Add Records | Captain Docs

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.post(
    f"{BASE_URL}/v1/indexes/{INDEX}/records",
    headers=headers,
    json=[
        {
            "id": "sku-20001",
            "title": "Speedcross 6 Trail Running Shoe",
            "brand": "Salomon",
            "category": "Trail Running Shoes",
            "price": 139.0,
            "color": "black",
        },
        {
            "id": "sku-10482",
            "title": "Moab 3 Mid Waterproof Hiking Boot",
            "brand": "Merrell",
            "category": "Hiking Boots",
            "price": 129.0,
            "color": "brown",
        },
    ],
    timeout=30.0,
)
print(json.dumps(response.json(), indent=2))

{
  "index": "products",
  "accepted": 2,
  "new": 1,
  "replaced": 1,
  "record_count": 12841,
  "max_records": 20000,
  "rejected": [],
  "rejected_count": 0,
  "duplicates": 0,
  "warnings": [],
  "seq": 1842,
  "accepted_at": 1759095298.114,
  "regions_applied": [
    "us-east-1"
  ],
  "regions_pending": [
    "us-west-1",
    "us-east-2"
  ]
}

Add records, or replace records with the same id. They become searchable within a few seconds. Send a JSON array (up to 1,000 records and 8 MiB), NDJSON (one record per line, up to 100,000 records and 64 MiB) or CSV with a header row (the NDJSON limits). Each record is a JSON object with an id and the index’s fields. See Records for how to structure a record.

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

on_errorenumOptionalDefaults to fail

fail: one bad record rejects the request (400, details names every bad row). skip: the good records are added and the bad ones returned in rejected

Allowed values:

on_duplicateenumOptionalDefaults to warn

an id sent more than once in one upload. warn: the last copy is kept and the answer carries duplicates and a DUPLICATE_ID warning. fail: the request is rejected (400, details names each repeated id and its lines)

Allowed values:

line_offsetintegerOptional>=0Defaults to 0

CSV: added to every line the answer names, so a client that splits a big file (repeating the header) reports the file’s own lines

Request

This endpoint expects a list of objects.

Response

Accepted. The records are searchable within a few seconds.

indexstringOptional

acceptedintegerOptional

Records accepted from this request.

newintegerOptional

Accepted records with an id the index did not have.

replacedintegerOptional

Accepted records that replaced a record with the same id.

record_countintegerOptional

Records the index holds after this request, built or not.

max_recordsintegerOptional

The most records the index can hold.

rejectedlist of objectsOptional

on_error=skip: the first 100 rows left out

rejected_countintegerOptional

on_error=skip: every row left out

id_suggestionobjectOptional

every record lacked the id field: the field the data points to, for you to name as id_field when creating the index (nothing is set for you)

duplicatesintegerOptional

records that repeat an id sent earlier in this upload (the last copy is kept); 0 when none. A repeat across uploads is a replace, counted in replaced

warningslist of objectsOptional

DUPLICATE_ID when duplicates > 0: count, ids (the first 20, each with its lines or indexes) and message

seqintegerOptional

This change's place in order. Get Update Status reports the last applied seq.

accepted_atdoubleOptional

regions_appliedlist of stringsOptional

regions_pendinglist of stringsOptional

Authentication

Path parameters

Headers

Query parameters

Request

Response