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

# Client

`Client` is the entry point of the CyborgDB JS/TS SDK. It connects to a running CyborgDB service and creates, loads, and lists encrypted indexes. Operations on an index, such as upsert and query, are methods of the `EncryptedIndex` it returns.

## Constructor

```typescript theme={null}
new Client({
    baseUrl: string,
    apiKey?: string,
    verifySsl?: boolean,
})
```

### Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `baseUrl` | `string` | - | Base URL of the CyborgDB service, e.g. `'http://localhost:8000'`. Must use `http://` or `https://`. |
| `apiKey` | `string` | `undefined` | *(Optional)* Service authentication credential, sent as the `X-API-Key` header. Required only when the service has authentication enabled. |
| `verifySsl` | `boolean` | `undefined` (auto-detect) | *(Optional)* TLS certificate verification. See [TLS verification](#tls-verification). |

<Note>`apiKey` is the service **authentication** credential: the root key or a per-user `cdbk_` token. It is required only when the service runs with `CYBORGDB_SERVICE_ROOT_KEY` set; against an unauthenticated service (the default), omit it. This is distinct from the service's `CYBORGDB_API_KEY` license key. See [Managing Keys](../../guides/advanced/managing-keys).</Note>

The constructor throws `CyborgDBValidationError` if `baseUrl` can't be parsed or doesn't use `http://` or `https://`.

### Example Usage

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

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

## TLS verification

`verifySsl` decides whether the SDK checks the service's TLS certificate:

| `baseUrl` | `verifySsl` unset | `true` | `false` |
| - | - | - | - |
| `http://…` | No TLS | No TLS | No TLS |
| `https://` with host `localhost`, `127.0.0.1`, or `::1` | Verification **off** | Verification on | Verification off |
| Any other `https://` URL | Verification on | Verification on | Verification off |

Turning verification off works on Node.js, where requests then go through the `node:https` module instead of `fetch`. It follows redirects and honors `AbortSignal`, and it times out a connection after 300 seconds of inactivity. Browsers and Edge runtimes can't turn verification off; `verifySsl: false` has no effect there.

When verification is off, the SDK logs `console.warn` messages: on Node, one saying verification is disabled and a second saying the insecure transport is in use. The loopback auto-detect case logs its first message with `console.info`. A plain `http://` URL also logs "SSL verification is disabled", although there is no TLS to disable.

## Errors

Failed requests throw a subclass of `CyborgDBError` chosen by HTTP status, such as `CyborgDBNotFoundError` for `404` or `CyborgDBAuthenticationError` for `401`. Arguments rejected inside the SDK, before a request is sent, throw `CyborgDBValidationError`. See [Errors](../errors) for the full list.

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

try {
    await new Client({ baseUrl: 'http://localhost:8000', apiKey: 'wrong-key' }).listIndexes();
} catch (error) {
    console.log(error instanceof CyborgDBAuthenticationError);
}
// Output: true
```

## Supported runtimes

The package has no runtime dependencies and needs only `fetch` and Web Crypto, so it runs on:

| Runtime | Notes |
| - | - |
| Node.js 18+ | Full functionality, including the on-disk [sample dataset](../load-sample-dataset) cache. |
| Bun, Deno | Same as Node. |
| Modern browsers | No sample-dataset cache. |
| Vercel Edge Runtime, Cloudflare Workers | No sample-dataset cache. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.