> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Train Index

Train an index for efficient querying. Required before optimal performance.

## Authentication

Required - **admin (root) API key** via `X-API-Key` header. Per-user (`cdbk_`) keys are rejected with `403` — a per-user credential operates on data, not index lifecycle:

```http theme={null}
X-API-Key: cyborg_your_api_key_here
```

When RBAC is not enabled (`CYBORGDB_SERVICE_ROOT_KEY` unset), no header is required.

## Request Body

```json theme={null}
{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "n_lists": null,
  "batch_size": 2048,
  "max_iters": 100,
  "tolerance": 0.000001,
  "max_memory": 0
}
```

<Expandable title="parameters">
  <ParamField body="index_name" type="string" required="true">
    Name of the index to train
  </ParamField>

  <ParamField body="index_key" type="string">
    32-byte encryption key as a hex string. Required for indexes created with the SDK-supplied KEK path; omit for KMS-backed indexes (the service resolves the key from the index's stored key envelope).
  </ParamField>

  <ParamField body="n_lists" type="integer" default="null (auto)">
    Number of inverted lists to create. When `null` or omitted, automatically determines optimal value based on dataset size
  </ParamField>

  <ParamField body="batch_size" type="integer" default={2048}>
    Size of each training batch. **Currently ignored** — see warning below
  </ParamField>

  <ParamField body="max_iters" type="integer" default={100}>
    Maximum training iterations. **Currently ignored** — see warning below
  </ParamField>

  <ParamField body="tolerance" type="number" default={1e-6}>
    Convergence tolerance. **Currently ignored** — see warning below
  </ParamField>

  <ParamField body="max_memory" type="integer" default={0}>
    Maximum memory usage in MB (0 = no limit). **Currently ignored** — see warning below
  </ParamField>
</Expandable>

<Warning>
  Only `index_name`, `index_key`, and `n_lists` affect training. The remaining parameters — `batch_size`, `max_iters`, `tolerance`, and `max_memory` — are accepted and validated but **not applied**: the training job silently drops them and runs with built-in defaults. Sending them does not cause an error, but it has no effect. This will be fixed in an upcoming update.
</Warning>

## Response

**Training Completed:**

```json theme={null}
{
  "status": "success",
  "message": "Index 'my_index' trained successfully"
}
```

**Training Failed:**

```json theme={null}
{
  "status": "error",
  "message": "Training failed for 'my_index': internal error during training"
}
```

<Note>
  This endpoint blocks until training completes. It will return `"success"` when training finishes normally, or `"error"` if the training job fails — both as HTTP `200`, never an HTTP error status. The `"error"` message is generic; the underlying cause is written to the service logs, not the response. HTTP error codes below only cover failures *before* the job runs (auth, unknown index, malformed request).

  **Too few vectors is not reported as an error.** When the index holds fewer vectors than the training minimums (see [Training Requirements](#training-requirements)), the job skips training silently and still returns `"status": "success"` — the only trace is a warning in the service logs. Check your vector count before training.
</Note>

## Exceptions

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Authentication failed (invalid API key) **or** wrong `index_key` on SDK-supplied indexes — see [error model](../introduction#error-model-api-keys-index-keys-and-kms)
  </Accordion>

  <Accordion title="403 Forbidden">
    Authenticated with a per-user (`cdbk_`) key — this operation requires the admin (root) API key
  </Accordion>

  <Accordion title="404 Not Found">
    Index not found
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    Request body failed validation (missing/mistyped fields)
  </Accordion>

  <Accordion title="500 Internal Server Error">
    Internal server error
  </Accordion>
</AccordionGroup>

## Example Usage

**Basic Training:**

```bash theme={null}
curl -X POST "http://localhost:8000/v1/indexes/train" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here"
     }'
```

**Explicit `n_lists`:**

```bash theme={null}
curl -X POST "http://localhost:8000/v1/indexes/train" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "my_index",
       "index_key": "your_64_character_hex_key_here",
       "n_lists": 128
     }'
```

<Tip>There must be at least 10,000 vector embeddings in the index prior to training — and at least `2 × n_lists` if you set `n_lists` explicitly.</Tip>

## Training Requirements

* **Minimum vectors**: At least 10,000 vectors must be present in the index, and at least `2 × n_lists` when `n_lists` is set explicitly (the auto-computed `n_lists` always satisfies this). Below either floor the job **skips training silently** and still returns `200` with `"status": "success"` — the skip is only visible as a warning in the service logs
* **Memory**: Training may require significant memory depending on dataset size
* **Time**: Training duration varies based on dataset size and convergence parameters

## Use Cases

* **Performance optimization**: Enable fast approximate nearest neighbor search
* **Production preparation**: Train indexes before deploying to production
* **Batch processing**: Train indexes after bulk data ingestion
* **Index maintenance**: Retrain indexes after significant data updates


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.