# TypeScript SDK (/sdk/typescript)



The TypeScript SDK (`@zumik/sdk`) is a `fetch`-based client with no runtime dependencies. It exposes
the widest native surface of the four SDKs, grouped into typed sub-clients, and covers both `/v1` and
`/v2`.

## Install [#install]

```bash
npm install @zumik/sdk
```

ESM, types included. Works anywhere `fetch` is available (Node 18+ and the browser).

## Authenticate [#authenticate]

`apiKey` is required; `baseUrl` defaults to `https://api.zumik.ai`.

```typescript
import { ZumikClient } from "@zumik/sdk";

const client = new ZumikClient({ apiKey: "zk_live_..." });
// or: new ZumikClient({ apiKey, baseUrl, headers })
```

## /v1 OpenAI-compatible [#v1-openai-compatible]

The `v1` namespace mirrors the OpenAI surface:

```typescript
await client.v1.responses.create({ model: "code.balanced", input: "Review the latest patch." });
await client.v1.chatCompletions.create({
  model: "code.fast",
  messages: [{ role: "user", content: "hello there" }],
});
await client.v1.embeddings.create({ model: "auto.cheapest", input: "embed me" });
await client.v1.models.list();
```

## Native /v2 [#native-v2]

Each resource is its own namespace.

```typescript
const art = await client.artifacts.create({ artifact_type: "policy", content: "Run the linter before every commit." });
await client.artifacts.retrieve(art.id);

const bundle = await client.bundles.create({ items: [{ artifact_id: art.id, role: "system" }] });
const session = await client.sessions.create({ base_bundle_ids: [bundle.id] });

const resp = await client.responses.create({
  model: "code.fast",
  input: "Summarize the failing test.",
  session_id: session.id,
});
console.log(resp.output_text, resp.qos_outcome);
```

### Branches with compare-and-swap [#branches-with-compare-and-swap]

```typescript
const branch = await client.sessions.branches.create("ses_…", { fork_from_branch_id: session.default_branch_id });
const event = await client.sessions.branches.appendEvent("ses_…", branch.id, {
  expected_version: branch.version,
  expected_head_event_id: branch.head_event_id,
  event: { event_type: "user_message", payload_ref: art.id },
});
await client.sessions.branches.createSnapshot("ses_…", branch.id, { ordered_block_manifest: [art.id, event.id] });
```

A stale version throws `ZumikApiError` with `status === 409`.

### Diagnostics, purge, aliases [#diagnostics-purge-aliases]

```typescript
await client.diagnostics.create({ traces: [{
  trace_id: "trc_1", privacy_mode: "metadata", prefix_family_id: "pf_a",
  observed: { resolved_target: "openai/gpt-4o@2025-01-01", ttft_ms: 410, latency_ms: 2880,
              input_tokens: 18000, candidate_reuse_tokens: 17000,
              realized_reused_tokens: 15000, output_tokens: 400, attempt_count: 1 },
}] });

const job = await client.purgeJobs.create({ artifact_ids: [art.id] });
await client.purgeJobs.receipt(job.id);

await client.modelAliases.list();
await client.tokenCounts.create({ input: "count me" });
```

## Namespaces [#namespaces]

| Namespace            | Methods                                               |
| -------------------- | ----------------------------------------------------- |
| `v1.responses`       | `create`, `retrieve`, `cancel`, `inputTokens`         |
| `v1.chatCompletions` | `create`                                              |
| `v1.embeddings`      | `create`                                              |
| `v1.models`          | `list`, `retrieve`                                    |
| `artifacts`          | `create`, `retrieve`, `delete`                        |
| `bundles`            | `create`, `retrieve`, `delete`                        |
| `sessions`           | `create`, `retrieve`, `delete`                        |
| `sessions.branches`  | `create`, `retrieve`, `appendEvent`, `createSnapshot` |
| `snapshots`          | `retrieve`                                            |
| `responses`          | `create`, `retrieve`, `cancel`                        |
| `diagnostics`        | `create`                                              |
| `purgeJobs`          | `create`, `retrieve`, `receipt`                       |
| `modelAliases`       | `list`, `retrieve`                                    |
| `tokenCounts`        | `create`                                              |

The `artifact_type` and `retention_class` unions, and the `DiagnosticTrace` shape, are fully typed.

## Error handling [#error-handling]

A non-2xx response throws `ZumikApiError` with `status` and `payload`:

```typescript
import { ZumikApiError } from "@zumik/sdk";

try {
  await client.artifacts.create({ artifact_type: "policy", content: "" });
} catch (e) {
  if (e instanceof ZumikApiError) console.error(e.status, e.payload);
}
```

The SDK does not stream or retry. For streamed chat completions, use the official `openai` package
against the `/v1` base URL - see [Using the OpenAI SDK](/integrations/openai-sdk).