Skip to main content
POST
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:
When RBAC is not enabled (CYBORGDB_SERVICE_ROOT_KEY unset), no header is required.

Request Body

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.

Response

Training Completed:
Training Failed:
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), 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.

Exceptions

Authentication failed (invalid API key) or wrong index_key on SDK-supplied indexes — see error model
Authenticated with a per-user (cdbk_) key — this operation requires the admin (root) API key
Index not found
Request body failed validation (missing/mistyped fields)
Internal server error

Example Usage

Basic Training:
Explicit n_lists:
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.

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