Node SDK

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

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. The two are separate packages targeting separate runtimes.

Install

npm install @kataven/server

Quickstart

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 for the full table. Resource names are camelCase in TS:

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

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;
}

Get started

Resource reference

Install

Quickstart

Environment variables

Resources

Errors

​Install

​Quickstart

​Environment variables

​Resources

​Errors

Install

Quickstart

Environment variables

Resources

Errors