Skip to main content
POST
Upsert Vectors (Binary)
Add new vectors or update existing ones in the encrypted index using a binary-encoded format for more efficient transfer of large batches.

Authentication

Required - API key via X-API-Key header:
Any valid credential is accepted — the root key or a per-user cdbk_ token. When RBAC is not enabled (CYBORGDB_SERVICE_ROOT_KEY unset), no header is required.

Request Body

Response

With Auto-Training Triggered:
With Training Check Warning:
In rare cases where the training check encounters an error but the upsert operation itself succeeds, a warning field will be included instead. The vectors are still successfully upserted in this scenario.

Exceptions

Invalid values (e.g. vector dimension mismatch with the index)
Authentication failed (invalid API key) or wrong index_key on SDK-supplied indexes — see error model
Index not found
Request body failed validation (missing/mistyped fields)
Internal server error

Example Usage

The binary format is more efficient than the standard JSON upsert for large batches, as it avoids the overhead of encoding each float as a JSON number. The SDK clients automatically use this format when vectors are passed as typed arrays (e.g., np.ndarray in Python, Float32Array in JS/TS).