@karta.sh/sdk

@karta.sh/sdk is a small, zero-dependency TypeScript client for managing your Karta account: 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 agent through a consumer adapter with the OpenAI or Anthropic SDK.

Install & construct

npm install @karta.sh/sdk

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

const karta = new Karta({
  apiKey: process.env.KARTA_API_KEY!,        // kt_live_... bearer token (required)
  baseUrl: "https://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.

Resource	Methods	Scope normally needed
`apiKeys`	`list`, `create`, `rename`, `revoke`	`read`, `keys:write`, or `admin` depending on the operation.
`modelKeys`	`list`, `create`, `revoke`	`model_keys:read` / `model_keys:write` or `admin`.
`webhookEndpoints`	`list`, `create`, `update`, `delete`	`webhooks:read` / `webhooks:write` or `admin`.
`usage`	`summary`	`analytics:read` or `admin`.
`billing`	`status`	`billing:read` or `admin`.

API keys

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

Model keys (BYOK)

await karta.modelKeys.create({
  provider: "xai",
  name: "production-xai",
  plaintext: process.env.XAI_API_KEY!,
  endpoint_url: "https://api.x.ai/v1",
  api_format: "openai_responses",
});
await karta.modelKeys.list();
await karta.modelKeys.revoke(id);

Providers: anthropic, openai, bedrock, vertex, openrouter, xai, and google. Connector creation accepts an optional HTTPS endpoint_url and an explicit api_format. See BYOK.

Webhook endpoints

const { webhook_endpoint, secret } = await karta.webhookEndpoints.create({
  url: "https://example.com/webhooks/karta",
  event_types: ["subscription.created", "invoice.paid"],
});
await karta.webhookEndpoints.update(webhook_endpoint.id, { re_enable: true });
await karta.webhookEndpoints.delete(webhook_endpoint.id);

update only re-enables a disabled endpoint; event types are set at create. 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.sh/sdk";

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

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

const usage = await karta.usage.summary();
console.log(`Requests this period: ${usage.totals.requests ?? 0}`);

Python SDK

TypeScript

Chat Widget

@karta.sh/sdk

Install & construct

API keys

Model keys (BYOK)

Webhook endpoints

Usage & billing

Full example

​Install & construct

​API keys

​Model keys (BYOK)

​Webhook endpoints

​Usage & billing

​Full example

Install & construct

API keys

Model keys (BYOK)

Webhook endpoints

Usage & billing

Full example