Create Index

POST

indexes

create

Create Index

curl --request POST \
  --url https://api.example.com/v1/indexes/create

import requests

url = "https://api.example.com/v1/indexes/create"

response = requests.post(url)

print(response.text)

const options = {method: 'POST'};

fetch('https://api.example.com/v1/indexes/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/indexes/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/indexes/create"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/indexes/create")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/indexes/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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"
}

Show parameters

index_name

string

required

Unique name for the index.

index_key

string

32-byte encryption key as a hex string. Required when kms_name is omitted (SDK-supplied KEK path). Must be omitted when kms_name is set against a real KMS provider — supplying both is rejected with 400.

kms_name

string

Name of a kms.registry entry in the service YAML configuration. When supplied, the service generates a fresh KEK, wraps it under the named provider (e.g. aws-kms), and persists the envelope. The SDK never sees the plaintext key. Mutually exclusive with index_key against a real provider.

dimension

integer

Vector dimensionality. If omitted, the server auto-detects from the first upsert.

metric

string

Distance metric. Options: euclidean, squared_euclidean, cosine. Defaults to the server’s default (euclidean).

embedding_model

string

Optional sentence-transformers model name for automatic embedding generation on upsert/query. When set, dimension is inferred from the model and may be omitted.

storage_precision

string

On-disk rerank-vector dtype. Accepts "float32" (default) or "float16". Use "float16" to halve storage at the cost of small recall.

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.

Health Check

List Indexes

⌘I

Introduction

Client

Encrypted Index

Types & Getters

Users (RBAC)

Request Body

Key Management Modes

Response

Exceptions

Example Usage

​Request Body

​Key Management Modes

​Response

​Exceptions

​Example Usage

Request Body

Key Management Modes

Response

Exceptions

Example Usage