> ## 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.sh/sdk

> The TypeScript client for account operations - API keys, BYOK, webhooks, usage, and billing.

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

<Note>
  This SDK manages your **account**. It does not send chat messages - for
  sessions and streaming, call the [HTTP API](/api-reference/introduction)
  directly, or hit your agent through a
  [consumer adapter](/api-reference/adapters/overview) with the OpenAI or
  Anthropic SDK.
</Note>

## Install & construct

```bash theme={null}
npm install @karta.sh/sdk
```

```typescript theme={null}
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

```typescript theme={null}
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)

```typescript theme={null}
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](/platform/byok).

## Webhook endpoints

```typescript theme={null}
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](/platform/webhooks).

## Usage & billing

```typescript theme={null}
const usage = await karta.usage.summary();      // period totals + budget
const billing = await karta.billing.status();   // subscription state
```

See [Usage & budgets](/platform/usage-and-budgets).

## Full example

```typescript theme={null}
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}`);
```