Create Index

Create a new encrypted index.

There is a single index type. Configuration parameters (dimension, metric, embedding_model, storage_precision) are top-level fields; the index_config object and the IVFFlat/IVFPQ/IVFSQ distinction from earlier versions no longer apply.

Authentication

Required - admin (root) API key via X-API-Key header. Per-user (cdbk_) keys are rejected with 403 — a per-user credential operates on data, not index lifecycle:

X-API-Key: cyborg_your_api_key_here

When RBAC is not enabled (CYBORGDB_SERVICE_ROOT_KEY unset), no header is required.

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",
  "metadata_schema": {
    "title": {"filterable": true, "pattern": true},
    "internal_blob": {"filterable": false}
  }
}

Show parameters

string

required

Unique name for the index.

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 — supplying both is always rejected with 400.

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.

integer

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

string

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

string

Optional embedding model name for automatic embedding generation on upsert/query. Must be one of the built-in models returned by List Embedding Models. When set, dimension is inferred from the model and may be omitted.

string

On-disk rerank-vector dtype. Accepts "float32" (default), "float16", or the TurboQuant tiers "tq12", "tq8", "tq6", "tq4". Lower precisions reduce storage at the cost of small recall — "float16" halves it; the tq* tiers compress further (12, 8, 6, or 4 bits per component).

object

Per-field metadata indexing policy, keyed by field name (dot-paths for nested fields). Fixed at create time and immutable. Fields omitted here inherit the default (indexed and filterable). See Metadata Schema below.

Show MetadataFieldPolicy

boolean

default:true

Index the field so filters on it resolve from the index. When false, the field is still stored and still filterable via post-filter on /v1/vectors/query, but cannot be filtered on /v1/vectors/query_metadata.

boolean

default:false

Additionally build the field’s regex dictionary, needed for index-resolved $regex / $contains. Requires filterable=true.

boolean

default:false

Route the field’s string value through the BM25 analyzer instead of exact-match indexing, making it searchable via text on /v1/vectors/query and /v1/vectors/query_metadata. A field is either analyzed or exact-match indexed, so full_text: true implies filterable: false and is incompatible with pattern: true.

array[string]

Fields to index for BM25 full-text search — shorthand for marking them full_text: true in metadata_schema. Enables text queries on /v1/vectors/query and /v1/vectors/query_metadata.

number

BM25 term-frequency saturation (>= 0, default 1.2). Requires at least one full_text field.

number

BM25 length-normalization strength (in [0, 1], default 0.75). Requires at least one full_text field.

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 from the index’s stored key envelope.

Supplying both is rejected with 400, regardless of the registry slot’s provider type. (The none provider is not addressable by name — omit kms_name to use the SDK-supplied path.)

Metadata Schema

metadata_schema sets the per-field indexing policy. Metadata itself stays schemaless — this controls how each field is indexed, not what may be stored. Three knobs per field:

filterable (default true) — index the field so filters on it resolve from the index (pre-filter, and the only path /v1/vectors/query_metadata uses). false still stores the field but forces the dense post-filter path when /v1/vectors/query filters reference it — cheaper writes, slower filtered queries.
pattern (default false) — additionally build the field’s regex dictionary, needed for index-resolved $regex / $contains. Requires filterable: true.
full_text (default false) — route the field through the BM25 analyzer for full-text search instead of exact-match indexing. Implies filterable: false and is incompatible with pattern: true.

On /v1/vectors/query the schema is a performance hint: filters that miss the index fall back to a post-filter over the decrypted metadata, same rows either way. On /v1/vectors/query_metadata it is enforced — $regex / $contains on a non-pattern field, or any filter on a filterable: false field, is rejected with 400. The recorded policy is echoed back on POST /v1/indexes/describe under metadata_schema (empty object when the index uses the default posture).

Response

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

Exceptions

400 Bad Request

Index name already exists. Also raised for missing/conflicting key parameters (both index_key and kms_name supplied, or neither), and for BM25 parameter violations: bm25_k1 / bm25_b supplied for an index with no full_text field, bm25_k1 < 0, bm25_b outside [0, 1], or a text_fields entry naming a field the schema sets full_text=false

401 Unauthorized

Authentication failed (invalid API key)

403 Forbidden

Authenticated with a per-user (cdbk_) key — this operation requires the admin (root) API key

422 Unprocessable Entity

Invalid request parameters — including metadata_schema with pattern=true but filterable=false, full_text=true combined with pattern=true or an explicit filterable=true, an empty field name, or an empty text_fields entry

500 Internal Server Error

Internal server error

502 Bad Gateway

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

With per-field metadata policy:

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": "docs_index",
       "index_key": "your_64_character_hex_key_here",
       "dimension": 384,
       "metadata_schema": {
         "title": {"filterable": true, "pattern": true},
         "internal_blob": {"filterable": false}
       }
     }'

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.

Introduction

Client

Encrypted Index

Types & Getters

Users (RBAC)

Authentication

Request Body

Key Management Modes

Metadata Schema

Response

Exceptions

Example Usage

​Authentication

​Request Body

​Key Management Modes

​Metadata Schema

​Response

​Exceptions

​Example Usage

Authentication

Request Body

Key Management Modes

Metadata Schema

Response

Exceptions

Example Usage