Skip to main content
POST
/
v1
/
indexes
/
create
Create Index
curl --request POST \
  --url https://api.example.com/v1/indexes/create
Create a new encrypted DiskIVF index.
v0.17 introduces a single DiskIVF index type and removes the polymorphic index_config object from previous versions. Configuration parameters (dimension, metric, embedding_model, storage_precision) are now top-level fields. The IVFFlat/IVFPQ/IVFSQ distinction no longer applies.

​
Request Body

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "dimension": 384,
  "metric": "euclidean",
  "embedding_model": "all-MiniLM-L6-v2",
  "storage_precision": "float32"
}

​
Key Management Modes

Exactly one of index_key / kms_name must be supplied:
  • SDK-supplied KEK (set index_key, omit kms_name) — the service records the index with provider: none. The same key must be re-supplied on every subsequent request (load, query, upsert, etc.).
  • KMS-backed (set kms_name, omit index_key) — the service generates the KEK, wraps it under the named registry slot, and persists the envelope. Subsequent requests omit index_key entirely; the service resolves it via the stored KMSBlob.
Supplying both against a real-KMS slot is rejected with 400. (The none provider is not addressable by name — omit kms_name to use the SDK-supplied path.)

​
Response

{
  "status": "success",
  "message": "Index 'my_index' created successfully"
}

​
Exceptions

  • 400: Missing/conflicting key parameters (e.g. both index_key and kms_name against a real KMS slot, or neither supplied)
  • 401: Authentication failed (invalid API key)
  • 409: Index name already exists
  • 422: Invalid request parameters
  • 500: Internal server error
  • 502: KMS error (e.g. wrap operation failed)

​
Example Usage

Basic (SDK-supplied key): 
curl -X POST "http://localhost:8000/v1/indexes/create" \
     -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",
       "dimension": 384
     }'
KMS-backed: 
curl -X POST "http://localhost:8000/v1/indexes/create" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "kms_index",
       "kms_name": "prod-aws",
       "dimension": 384
     }'
With auto-embedding: 
curl -X POST "http://localhost:8000/v1/indexes/create" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "semantic_index",
       "index_key": "your_64_character_hex_key_here",
       "embedding_model": "all-MiniLM-L6-v2"
     }'
Float16 storage for reduced footprint: 
curl -X POST "http://localhost:8000/v1/indexes/create" \
     -H "X-API-Key: cyborg_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "index_name": "compact_index",
       "index_key": "your_64_character_hex_key_here",
       "dimension": 768,
       "storage_precision": "float16"
     }'
When embedding_model is specified, dimension is optional — the server infers it from the model. The index will automatically generate embeddings for text content during upsert operations.