Skip to main content
POST
/
v1
/
vectors
/
upsert_binary
Upsert Vectors (Binary)
curl --request POST \
  --url https://api.example.com/v1/vectors/upsert_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: 
X-API-Key: cyborg_your_api_key_here
You can get an API key from the CyborgDB Admin Dashboard. For more info, follow this guide.

​
Request Body

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "batch": {
    "ids": ["item_1", "item_2"],
    "vectors_b64": "BASE64_ENCODED_FLOAT32_ARRAY",
    "dimension": 384,
    "metadata": [
      {"category": "greeting", "language": "en"},
      {"category": "greeting", "language": "fr"}
    ],
    "contents": ["Hello world!", "Bonjour monde!"]
  }
}

​
Response

{
  "status": "success",
  "message": "Upserted 2 vectors"
}
With Auto-Training Triggered: 
{
  "status": "success",
  "message": "Upserted 2 vectors",
  "training_triggered": true,
  "training_message": "Index training has been triggered (vectors: 5000, threshold: 10000)"
}

​
Exceptions

  • 401: Authentication failed (invalid API key) or wrong index_key on SDK-supplied indexes — see error model
  • 404: Index not found
  • 422: Invalid request parameters or vector dimensions
  • 500: Internal server error

​
Example Usage

# Encode vectors as base64 float32 array (example using Python)
# vectors = np.array([[0.1, 0.2, 0.3, 0.4], [0.5, 0.6, 0.7, 0.8]], dtype=np.float32)
# vectors_b64 = base64.b64encode(vectors.tobytes()).decode()

curl -X POST "http://localhost:8000/v1/vectors/upsert_binary" \
     -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",
       "batch": {
         "ids": ["item_1", "item_2"],
         "vectors_b64": "zczMPc3MTD6amZk+zczMPgAAAD+amRk/MzMzP83MTD8=",
         "dimension": 4
       }
     }'
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).