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

# Node SDK

> Official Node / TypeScript server SDK for the Kataven Hub API.

`@kataven/server` is the **server-side** TypeScript client. It mirrors
the Python SDK feature-for-feature and shares the same OpenAPI spec
as its source of truth.

<Note>
  This is the **server** SDK — for managing agents, tools, telephony,
  campaigns, etc. from your backend. For the **browser** widget that
  talks to your agents via WebRTC, see
  [`@kataven/client`](https://www.npmjs.com/package/@kataven/client).
  The two are separate packages targeting separate runtimes.
</Note>

## Install

```bash theme={null}
npm install @kataven/server
```

## Quickstart

```ts theme={null}
import { Kataven } from "@kataven/server";

const client = new Kataven({
  apiKey: process.env.KATAVEN_API_KEY!,
  accountId: process.env.KATAVEN_ACCOUNT_ID!,
});

const agents = await client.agents.list();
console.log(agents);

const agent = await client.agents.create({
  name: "Front Desk",
  system_prompt: "You are a friendly receptionist.",
  greeting_message: "How can I help?",
  llm_model: "gpt-4o",
  voice_provider: "cartesia",
});
```

## Environment variables

The client falls back to env vars if not passed explicitly:

| Variable             | Default                     |
| -------------------- | --------------------------- |
| `KATAVEN_API_KEY`    | (required)                  |
| `KATAVEN_ACCOUNT_ID` | (required)                  |
| `KATAVEN_BASE_URL`   | `https://api.kataven.ai/v1` |

## Resources

Same set as the Python SDK — see the [Python overview](/sdks/python/overview)
for the full table. Resource names are camelCase in TS:

```ts theme={null}
client.agents.list()
client.agents.create({...})
client.tools.list({ category: "calendar" })
client.telephony.createNumber({...})
client.campaigns.create({...})
client.calls.originate({...})
client.widgetKeys.create({ name: "site", domain_allowlist: ["https://acme.com"] })
client.widgetSettings.update({ primary_color: "#2563eb" })
```

**API key (sk\_live\_) management is deliberately not in the SDK.** A
leaked `sk_live_` shouldn't be able to mint another `sk_live_`; the
server returns `403 Forbidden` on those operations for `sk_live_`
callers. Manage keys at **Hub UI → Settings → API Keys**.

**Other operations intentionally not in the SDK** (admin / dashboard-only):
`client.config`, `client.settings`, `client.spokes`, `client.users`,
`client.accounts`, `client.apiKeys`, `recordings.delete`, `callLimits.update`,
`marketplace.createTemplate`, `integrations.create`.

## Errors

```ts theme={null}
import { KatavenError, NotFoundError, RateLimitError } from "@kataven/server";

try {
  await client.agents.get("missing-id");
} catch (e) {
  if (e instanceof NotFoundError) console.log("not found");
  else if (e instanceof RateLimitError) console.log("cap exceeded");
  else throw e;
}
```