TypeScript SDK

Install @zumik/sdk, authenticate, and call the full /v1 OpenAI-compatible surface plus native /v2 artifacts, bundles, sessions, responses, diagnostics, and purge from Node or the browser.

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

npm install @zumik/sdk

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

Authenticate

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

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

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

/v1 OpenAI-compatible

The v1 namespace mirrors the OpenAI surface:

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

Each resource is its own namespace.

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

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

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

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

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

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.

TypeScript SDK

On this page