# TypeScript SDK (/docs/sdks/typescript)

> The @omnidim-ai/sdk package. A typed, server-side SDK for the OmniDimension API.

`@omnidim-ai/sdk` is the server-side SDK for the OmniDimension REST API.
Fully typed, and works in plain JavaScript too.

Run it on your backend with a secret API key. For a browser experience,
use the [web widget](/docs/sdks/web-widget).

## Installation [#installation]

```bash
npm install @omnidim-ai/sdk
```

Requires Node.js 20 or later. Package details and version history live at
[npmjs.com/package/@omnidim-ai/sdk](https://www.npmjs.com/package/@omnidim-ai/sdk).

## Initialization [#initialization]

Get an API key by following [Authentication](/docs/get-started/authentication), then create a client:

```ts
import OmniDimension from '@omnidim-ai/sdk';

const client = new OmniDimension({ apiKey: process.env.OMNIDIM_API_KEY! });

const agents = await client.agents.list({ pagesize: 10 });
```

Using plain JavaScript? Drop the `!` and the rest is identical:

```js
const client = new OmniDimension({ apiKey: process.env.OMNIDIM_API_KEY });
```

## Client structure [#client-structure]

```ts
client.agents          // Agent operations
client.calls           // Call dispatch and logs
client.bulkCalls       // Bulk-call campaigns
client.knowledgeBase   // Knowledge base files
client.phoneNumbers    // Phone numbers
client.providers       // LLM, voice, STT, TTS providers
client.integrations    // Integrations and agent attachment
client.reseller        // Partner operations (partner credentials required)
```

  " title="Agents" href="/docs/api-reference/agents/listAgents" description="Create, retrieve, update, and delete AI voice agents." />

  " title="Calls" href="/docs/api-reference/calls/dispatchCall" description="Dispatch calls and read call logs and transcripts." />

  " title="Knowledge base" href="/docs/api-reference/knowledge-base/listKnowledgeBaseFiles" description="Upload, attach, and manage knowledge base files." />

  " title="Phone numbers" href="/docs/api-reference/phone-numbers/listPhoneNumbers" description="List, attach, and import phone numbers." />

## Error handling [#error-handling]

Non-2xx responses and network failures throw `OmniDimensionError`:

```ts
import OmniDimension, { OmniDimensionError } from '@omnidim-ai/sdk';

const client = new OmniDimension({ apiKey: process.env.OMNIDIM_API_KEY! });

try {
  await client.agents.get(999);
} catch (err) {
  if (err instanceof OmniDimensionError) {
    console.error(err.status, err.message, err.body);
  }
}
```

`status` is the HTTP status code (0 for network or timeout errors).
`body` is the parsed error payload when present.

## Types [#types]

Schema types are exported for use in your own code:

```ts
import type { Agent, Call, Voice } from '@omnidim-ai/sdk';
```

## Client options [#client-options]

```ts
interface ClientOptions {
  // Your OmniDimension API key. Required.
  apiKey: string;
  // Override the API base URL. Defaults to production.
  baseURL?: string;
  // Per-request timeout in milliseconds. Defaults to 60000.
  timeout?: number;
  // Custom fetch implementation. Defaults to the global fetch.
  fetch?: typeof fetch;
  // Headers added to every request.
  defaultHeaders?: Record<string, string>;
}
```