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

# Load Index

Loads and connects to an existing encrypted index by name. `indexKey` is optional in v0.17: SDK-supplied indexes (`provider: none`) must pass the exact 32-byte key used at creation, while KMS-backed indexes omit it — the service resolves the KEK via the stored `KMSBlob`.

```typescript theme={null}
async loadIndex({
    indexName: string,       // required
    indexKey?: Uint8Array    // optional (see notes)
}): Promise<EncryptedIndex>
```

### Parameters

| Parameter   | Type         | Description                                                                                                                                                                              |
| ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indexName` | `string`     | Name of the existing index to load                                                                                                                                                       |
| `indexKey`  | `Uint8Array` | *(Optional)* The exact 32-byte encryption key used when creating the index. Required for indexes created with the SDK-supplied KEK path (`provider: none`); omit for KMS-backed indexes. |

<Note>In v0.17 `indexKey` is optional. KMS-backed indexes (created with `kmsName`) omit it — the server resolves the DEK via the persisted `KMSBlob`. SDK-supplied indexes must re-supply the same 32-byte key here.</Note>

<Warning>
  For SDK-supplied indexes, the encryption key must exactly match the key used during index creation. KMS-backed indexes are tied to their `kmsName` slot in the service YAML — load fails if that slot is missing or unreachable.
</Warning>

### Returns

`Promise<EncryptedIndex>`: A Promise that resolves to an `EncryptedIndex` instance ready for vector operations (query, upsert, delete, etc.)

### Exceptions

<AccordionGroup>
  <Accordion title="Error">
    * Throws if the index doesn't exist on the server
    * Throws if the encryption key is incorrect or invalid
    * Throws by the server if a KMS-backed index's slot is unavailable.
    * Throws if the server returns an HTTP error status.
    * Throws if authentication fails (invalid API key).
  </Accordion>

  <Accordion title="Service Errors">
    * Throws if the CyborgDB service is unavailable or unreachable.
    * Throws if there are internal server errors on the CyborgDB service.
  </Accordion>
</AccordionGroup>

### Example Usage

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

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

// Use the same key that was used to create the index
const indexKey = new Uint8Array(32); // Your stored 32-byte key
// Or convert from hex: Buffer.from('your-hex-key', 'hex')

// SDK-supplied index (legacy path) — supply the key
try {
    const index = await client.loadIndex({ indexName: 'my-existing-index', indexKey });
    console.log('Index loaded successfully');

    // Now you can perform operations on the loaded index
    const results = await index.query({ queryVectors: [0.1, 0.2, 0.3], topK: 5 });
    console.log('Query results:', results);
} catch (error) {
    console.error('Failed to load index:', error.message);
}

// KMS-backed index — no key required
const kmsIndex = await client.loadIndex({ indexName: 'kms-index' });
```