# SDKs (/sdk/overview)



Zumik ships four first-party SDKs. Each is a thin, dependency-light client over the same HTTP API: the OpenAI-compatible `/v1` surface and the native, stateful `/v2` surface. None of them reimplement an LLM client; they wrap the endpoints and get out of the way.

<CardGroup cols="2">
  <Card title="Python" icon="python" href="/sdk/python">
    `zumik` - synchronous, `httpx`-backed. The widest native coverage after TypeScript.
  </Card>

  <Card title="TypeScript" icon="js" href="/sdk/typescript">
    `@zumik/sdk` - `fetch`-based, zero runtime dependencies, the widest native surface.
  </Card>

  <Card title="Go" icon="golang" href="/sdk/go">
    `github.com/yethdev/Zumik/sdks/go` - standard library only, core flow.
  </Card>

  <Card title="Rust" icon="rust" href="/sdk/rust">
    `zumik-sdk` - async `reqwest`, core flow, returns `serde_json::Value`.
  </Card>
</CardGroup>

## Two surfaces, one platform [#two-surfaces-one-platform]

Every SDK talks to both public API surfaces:

* **`/v1` - OpenAI compatible.** Exact OpenAI request and response shapes. The compatibility contract means a vanilla OpenAI SDK works against `https://api.zumik.ai/v1` with only a base-URL swap, so the Zumik SDKs keep their `/v1` helpers deliberately thin. For the full OpenAI surface (streaming, the complete chat/embeddings options), point the official OpenAI client at the Zumik base URL - see [Using the OpenAI SDK](/integrations/openai-sdk) and [OpenAI compatibility](/openai-compatibility).
* **`/v2` - native and stateful.** Artifacts, bundles, sessions, branches, snapshots, native responses, diagnostics, token counts, and signed purge jobs as first-class objects. This is where the SDKs add real ergonomics.

The two interoperate: build state on `/v2`, then attribute `/v1` traffic to it with `Agent-*` headers. See [Core concepts](/concepts/overview).

## Install [#install]

<CodeGroup>
  ```bash title="Python"
  pip install zumik
  ```

  ```bash title="TypeScript"
  npm install @zumik/sdk
  ```

  ```bash title="Go"
  go get github.com/yethdev/Zumik/sdks/go
  ```

  ```toml title="Rust"
  # Cargo.toml
  [dependencies]
  zumik-sdk = "0.1.0"
  ```
</CodeGroup>

All four are at `0.1.0`. Python needs 3.9+ (`httpx` only); TypeScript is ESM and runs anywhere `fetch` exists (Node 18+ and the browser); Go needs 1.22+ with no third-party dependencies; Rust is async over `reqwest` and `serde_json`.

## Authenticate with ZUMIK\_API\_KEY [#authenticate-with-zumik_api_key]

Every SDK takes the API key as an explicit argument. None of them read the environment for you, which keeps the key out of accidental scope. Read `ZUMIK_API_KEY` yourself and pass it in:

<CodeGroup>
  ```python title="Python"
  import os
  from zumik import ZumikClient

  client = ZumikClient(api_key=os.environ["ZUMIK_API_KEY"])
  ```

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

  const client = new ZumikClient({ apiKey: process.env.ZUMIK_API_KEY! });
  ```

  ```go title="Go"
  import zumik "github.com/yethdev/Zumik/sdks/go"

  client := zumik.NewClient(os.Getenv("ZUMIK_API_KEY"))
  ```

  ```rust title="Rust"
  use zumik_sdk::Client;

  let client = Client::new(std::env::var("ZUMIK_API_KEY")?)?;
  ```
</CodeGroup>

The base URL defaults to `https://api.zumik.ai` in every SDK and is overridable for staging or a self-hosted deployment. The key is sent as a bearer token. See [Authentication](/authentication) for key formats, rotation, and per-key budgets.

## Capability matrix [#capability-matrix]

The TypeScript SDK has the broadest native coverage. Python is close behind. Go and Rust cover the core artifact-to-session-to-diagnose flow; anything not listed is reachable by calling the [HTTP API](/api-reference/introduction) directly with the client's underlying HTTP handle.

| Capability                                 | Python       | TypeScript | Go              | Rust        |
| ------------------------------------------ | ------------ | ---------- | --------------- | ----------- |
| `/v1` responses create / retrieve / cancel | Yes          | Yes        | create only     | create only |
| `/v1` input-token count                    | -            | Yes        | -               | -           |
| `/v1` chat completions                     | use `openai` | Yes        | use `openai-go` | use HTTP    |
| `/v1` embeddings                           | use `openai` | Yes        | use `openai-go` | use HTTP    |
| `/v1` models list / retrieve               | -            | Yes        | -               | -           |
| Artifacts create                           | Yes          | Yes        | Yes             | Yes         |
| Artifacts retrieve / delete                | -            | Yes        | -               | -           |
| Bundles create                             | Yes          | Yes        | Yes             | Yes         |
| Bundles retrieve / delete                  | -            | Yes        | -               | -           |
| Sessions create                            | Yes          | Yes        | Yes             | Yes         |
| Branches create (fork)                     | Yes          | Yes        | -               | -           |
| Append event (compare-and-swap)            | Yes          | Yes        | Yes             | Yes         |
| Snapshots create                           | Yes          | Yes        | Yes             | Yes         |
| Native `/v2` responses                     | Yes          | Yes        | -               | -           |
| Diagnostics                                | Yes          | Yes        | Yes             | Yes         |
| Token counts                               | Yes          | Yes        | -               | -           |
| Purge jobs + receipts                      | Yes          | Yes        | -               | -           |
| Model aliases                              | -            | Yes        | -               | -           |
| Built-in streaming                         | No           | No         | No              | No          |
| Built-in retries                           | No           | No         | No              | No          |

<Note>
  No SDK streams or retries on your behalf. For OpenAI-style streamed responses, use the official `openai` client against the `/v1` base URL ([details](/integrations/openai-sdk)). Add your own retry and timeout policy at the call site.
</Note>

## Picking a path [#picking-a-path]

<CardGroup cols="2">
  <Card title="I have an existing OpenAI app" icon="arrow-right-arrow-left" href="/guides/openai-migration">
    Swap the base URL on your current OpenAI client. No Zumik SDK needed for the `/v1` path.
  </Card>

  <Card title="I want native state" icon="layer-group" href="/concepts/overview">
    Use a Zumik SDK for `/v2` artifacts, sessions, branches, and diagnostics.
  </Card>
</CardGroup>