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

Creates and returns an `EncryptedIndex` instance backed by a new encrypted DiskIVF index on the server.

<Note>v0.17 introduces a single **DiskIVF** index type. The polymorphic `IndexIVFFlat` / `IndexIVFPQ` / `IndexIVFSQ` types and the `indexConfig` argument have been removed — index configuration is now expressed as flat keyword arguments (`dimension`, `metric`, `storagePrecision`).</Note>

```typescript theme={null}
async createIndex({
    indexName: string,                                      // required
    indexKey?: Uint8Array,                                  // optional (see Key Management)
    kmsName?: string,                                       // optional (see Key Management)
    dimension?: number,                                     // optional, auto-detected from first upsert
    metric?: 'euclidean' | 'squared_euclidean' | 'cosine',  // optional, defaults to server default ('euclidean')
    embeddingModel?: string,                                // optional
    storagePrecision?: 'float32' | 'float16'                // optional, defaults to 'float32'
}): Promise<EncryptedIndex>
```

### Parameters

| Parameter          | Type                                             | Description                                                                                                                                                                             |
| ------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indexName`        | `string`                                         | Name of the index to create. Must be unique within the CyborgDB service.                                                                                                                |
| `indexKey`         | `Uint8Array`                                     | *(Optional)* 32-byte encryption key. Required when `kmsName` is omitted. Must be omitted when `kmsName` references a real KMS provider.                                                 |
| `kmsName`          | `string`                                         | *(Optional)* Name of a `kms.registry` entry in the service YAML. When supplied, the server generates the KEK and wraps it via the named provider; the SDK never sees the plaintext key. |
| `dimension`        | `number`                                         | *(Optional)* Vector dimensionality. If omitted, the server auto-detects from the first upsert.                                                                                          |
| `metric`           | `'euclidean' \| 'squared_euclidean' \| 'cosine'` | *(Optional)* Distance metric. If omitted, the SDK does not set a value and the server applies its default.                                                                              |
| `embeddingModel`   | `string`                                         | *(Optional)* sentence-transformers model name for automatic embedding generation.                                                                                                       |
| `storagePrecision` | `'float32' \| 'float16'`                         | *(Optional)* On-disk rerank-vector dtype. Defaults to `'float32'`.                                                                                                                      |

### Key Management Modes

At least one of `indexKey` / `kmsName` must be supplied; supplying both against a real-KMS slot is rejected by the server:

* **SDK-supplied KEK** — pass `indexKey`, omit `kmsName`. The server records the index with `provider: none`; you must re-supply the same key on every subsequent call.
* **KMS-backed** — pass `kmsName`, omit `indexKey`. The server generates the DEK, wraps it under the named registry slot, and persists the envelope. Subsequent calls omit `indexKey` entirely.

### Returns

`Promise<EncryptedIndex>`: A Promise that resolves to a handle bound to the newly created index.

### Exceptions

<AccordionGroup>
  <Accordion title="Error">
    * Throws if neither `indexKey` nor `kmsName` is provided.
    * Throws if `indexKey` is provided but is not exactly 32 bytes.
    * Throws if the index name already exists on the server.
    * Throws if the embedding model is not supported by the server.
    * Throws if both `indexKey` and `kmsName` are provided against a real-KMS slot (rejected by the server with 400).
  </Accordion>

  <Accordion title="Service Errors">
    * Throws if the CyborgDB service is unavailable or unreachable.
    * Throws on 5xx responses, including KMS-wrap failures (502).
  </Accordion>
</AccordionGroup>

### Example Usage

#### SDK-supplied key

```typescript theme={null}
import { Client } from 'cyborgdb';

// Initialize client
const client = new Client({ baseUrl: 'http://localhost:8000', apiKey: 'your-api-key' });

// Generate a secure 32-byte encryption key
const indexKey: Uint8Array = client.generateKey();

// Create a basic index
const index = await client.createIndex({
    indexName: 'my_vector_index',
    indexKey,
    dimension: 384,
});
```

<Note>For more info on `generateKey`, refer to [Generate Key](./generate-key).</Note>

#### KMS-backed index

```typescript theme={null}
// The service generates the KEK, wraps it via the 'prod-aws' registry slot,
// and persists the envelope. The SDK never sees the plaintext key.
const index = await client.createIndex({
    indexName: 'kms_vector_index',
    kmsName: 'prod-aws',
    dimension: 384,
});
// Subsequent calls — including loadIndex — omit indexKey entirely.
```

#### With embedding model

```typescript theme={null}
// When embeddingModel is set, the server infers `dimension` from the model.
const index = await client.createIndex({
    indexName: 'semantic_search_index',
    indexKey,
    embeddingModel: 'all-MiniLM-L6-v2',
});
```

#### Float16 storage for reduced footprint

```typescript theme={null}
// Halves on-disk rerank-vector storage at the cost of small recall
const index = await client.createIndex({
    indexName: 'compact_index',
    indexKey,
    dimension: 768,
    storagePrecision: 'float16',
});
```

<Note>For more info on auto-generating embeddings, refer to [Auto-Generate Embeddings](../../guides/data-operations/add-items#automatic-embedding-generation).</Note>