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.

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/hub-api

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" })

Intentionally not in the SDK (admin / dashboard-only operations): client.config, client.settings, client.spokes, client.users, client.accounts, 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;
}