> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Index

Create a new encrypted DiskIVF index.

<Note>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.</Note>

## Request Body

```json theme={null}
{
  "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"
}
```

<Expandable title="parameters">
  <ParamField body="index_name" type="string" required="true">
    Unique name for the index.
  </ParamField>

  <ParamField body="index_key" type="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.
  </ParamField>

  <ParamField body="kms_name" type="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.
  </ParamField>

  <ParamField body="dimension" type="integer">
    Vector dimensionality. If omitted, the server auto-detects from the first upsert.
  </ParamField>

  <ParamField body="metric" type="string">
    Distance metric. Options: `euclidean`, `squared_euclidean`, `cosine`. Defaults to the server's default (`euclidean`).
  </ParamField>

  <ParamField body="embedding_model" type="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.
  </ParamField>

  <ParamField body="storage_precision" type="string">
    On-disk rerank-vector dtype. Accepts `"float32"` (default) or `"float16"`. Use `"float16"` to halve storage at the cost of small recall.
  </ParamField>
</Expandable>

## 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

```json theme={null}
{
  "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):**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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"
     }'
```

<Note>
  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.
</Note>