Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karta.sh/llms.txt

Use this file to discover all available pages before exploring further.

@karta/sdk is a small, zero-dependency TypeScript client for the control plane: managing API keys, BYOK provider keys, webhook endpoints, and reading usage and billing. It uses native fetch and ships full types.
This SDK manages your account. It does not send chat messages — for sessions and streaming, call the HTTP API directly, or hit your project through a consumer adapter with the OpenAI or Anthropic SDK.

​
Install & construct

npm install @karta/sdk

import { Karta } from "@karta/sdk";

const karta = new Karta({
  apiKey: process.env.KARTA_API_KEY!,        // kt_live_… bearer token (required)
  baseUrl: "https://api.karta.sh",          // optional
});
Requires Node ≥ 18.17 (for native fetch). Every 4xx/5xx throws a typed error (KartaAuthError, KartaForbiddenError, KartaNotFoundError, KartaValidationError) carrying status and the parsed body.

​
API keys

const keys = await karta.apiKeys.list();
const { api_key, secret } = await karta.apiKeys.create("ci-runner", ["write"]);
// `secret` is the plaintext kt_live_… — shown exactly once.
await karta.apiKeys.revoke(api_key.id);

​
Model keys (BYOK)

await karta.modelKeys.create("anthropic", process.env.ANTHROPIC_API_KEY!, "primary");
await karta.modelKeys.list();
await karta.modelKeys.revoke(id);
Providers: anthropic, openai, bedrock, vertex, openrouter. See BYOK.

​
Webhook endpoints

const { webhook_endpoint, secret } = await karta.webhookEndpoints.create({
  url: "https://example.com/karta-webhook",
  event_types: ["subscription.created", "invoice.paid"],
});
await karta.webhookEndpoints.update(webhook_endpoint.id, { event_types: [...] });
await karta.webhookEndpoints.delete(webhook_endpoint.id);
The returned secret (a whsec_…) verifies inbound signatures — see Webhooks.

​
Usage & billing

const usage = await karta.usage.summary();      // period totals + budget
const billing = await karta.billing.status();   // subscription state
See Usage & budgets.

​
Full example

import { Karta } from "@karta/sdk";

const karta = new Karta({ apiKey: process.env.KARTA_API_KEY! });

const { api_key, secret } = await karta.apiKeys.create("ci-runner", ["write"]);
await karta.modelKeys.create("anthropic", process.env.ANTHROPIC_API_KEY!, "primary");

const usage = await karta.usage.summary();
console.log(`Used ${usage} this period`);