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 index with the specified configuration.

Request Body

{
  "index_name": "my_index",
  "index_key": "64_character_hex_string_representing_32_bytes",
  "index_config": {
    "type": "ivfpq",
    "dimension": 384,
    "pq_dim": 64,
    "pq_bits": 8
  },
  "metric": "euclidean",
  "embedding_model": "all-MiniLM-L6-v2"
}

Show parameters

string

required

Unique name for the index

string

required

32-byte encryption key as hex string

object

Index configuration object. Optional when using embedding_model (defaults to IVFFlat). When provided, must contain:

type: Index type (ivfflat, ivfpq, ivfsq). ivf is also accepted but deprecated — use ivfflat instead.
dimension: Embedding dimension (optional)
pq_dim: Product quantization dimension (required for ivfpq)
pq_bits: Number of bits per sub-vector (required for ivfpq)
sq_bits: Number of bits per dimension for scalar quantization (required for ivfsq, default: 16) See Index Types for details.

string

Distance metric to use for the index. Options: euclidean, cosine, squared_euclidean. Defaults to euclidean

string

Optional sentence-transformers model for automatic embedding generation. When specified, dimension in index_config becomes optional as it will be inferred from the model

Index Types

IVFFlat (Recommended)

Suitable for applications requiring high recall with moderate memory usage:

{
  "type": "ivfflat",
  "dimension": 384
}

Speed: Fast | Recall: Highest | Index Size: Biggest

IVFSQ

Scalar Quantization compresses each dimension independently, balancing speed and index size:

{
  "type": "ivfsq",
  "dimension": 384,
  "sq_bits": 16
}

Speed: Fast | Recall: High | Index Size: Small

IVFPQ

Product Quantization compresses embeddings, balancing memory use and recall:

{
  "type": "ivfpq",
  "dimension": 384,
  "pq_dim": 64,
  "pq_bits": 8
}

Speed: Fast | Recall: High | Index Size: Medium

IVF (Deprecated)

The ivf type is deprecated. Use ivfflat instead, which provides equivalent functionality.

Distance Metrics

"euclidean": Euclidean distance
"cosine": Cosine similarity
"squared_euclidean": Squared Euclidean distance

Response

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

Exceptions

401: Authentication failed (invalid API key)
409: Index name already exists
422: Invalid request parameters
500: Internal server error

Example Usage

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",
       "index_config": {
         "type": "ivfflat",
         "dimension": 384
       }
     }'

With Auto-Embedding

# With explicit index config
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_search_index",
       "index_key": "your_64_character_hex_key_here",
       "index_config": {
         "type": "ivfflat"
       },
       "embedding_model": "all-MiniLM-L6-v2"
     }'

# Minimal configuration - index_config defaults to IVFFlat
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": "auto_index",
       "index_key": "your_64_character_hex_key_here",
       "embedding_model": "all-MiniLM-L6-v2"
     }'

When embedding_model is specified:

The dimension parameter in index_config is optional
The entire index_config object is optional (defaults to IVFFlat with auto-detected dimension)
The index will automatically generate embeddings for text content during upsert operations

Health Check

List Indexes

⌘I

Introduction

Client

Encrypted Index

Types & Getters

Request Body

Index Types

IVFFlat (Recommended)

IVFSQ

IVFPQ

IVF (Deprecated)

Distance Metrics

Response

Exceptions

Example Usage

With Auto-Embedding

​Request Body

​Index Types

​IVFFlat (Recommended)

​IVFSQ

​IVFPQ

​IVF (Deprecated)

​Distance Metrics

​Response

​Exceptions

​Example Usage

​With Auto-Embedding

Request Body

Index Types

IVFFlat (Recommended)

IVFSQ

IVFPQ

IVF (Deprecated)

Distance Metrics

Response

Exceptions

Example Usage

With Auto-Embedding