# SDKs

URL: https://docs.hanzo.ai/docs/sdks

> One generated client per language for the whole /v1 surface, plus the hand-written AI and per-service libraries for TypeScript. What each one is called on its registry, and the same first call in each.

Every Hanzo capability answers on one host under `/v1`, so a client for Hanzo is
a client for all of it. There is one such client per language, and it is
**generated** from the API's own OpenAPI document rather than written by hand —
which is why the class and the method you call follow from the operation instead
of from someone's taste, and why a capability that shipped this morning is in
the client without anyone adding it.

Beside those sit three hand-written TypeScript libraries that exist because they
are not projections of the document: an AI-shaped client, a per-service one, and
the IAM one. They are listed below with what each is for.

## The generated clients

The coordinate is the stable thing — the version moves every time cloud
releases, so it is not repeated here. Every one of these is cut from the same
document at a ref its own `.spec-lock` names.

| Language   | Coordinate                                                             | Install                                |
| ---------- | ---------------------------------------------------------------------- | -------------------------------------- |
| TypeScript | `hanzoai` on npm                                                       | `npm i hanzoai`                        |
| Python     | `hanzoai` on PyPI                                                      | `pip install "hanzoai>=8"`             |
| Go         | `github.com/hanzoai/go-sdk/v8`                                         | `go get github.com/hanzoai/go-sdk/v8`  |
| Rust       | `hanzo-client` on crates.io                                            | `cargo add hanzo-client`               |
| Swift      | [hanzo-swift/sdk](https://github.com/hanzo-swift/sdk), product `Hanzo` | SwiftPM, from the git URL              |
| Kotlin     | `ai.hanzo:hanzo-kotlin-cloud`                                          | Gradle, built from source              |
| Java       | `ai.hanzo:hanzo-java-cloud` on Maven Central                           | Gradle or Maven, from `mavenCentral()` |
| C++        | [hanzo-cpp/sdk](https://github.com/hanzo-cpp/sdk)                      | CMake, from a tag                      |

Swift, Kotlin and C++ are tagged and buildable but not on a package manager
that resolves them by name alone — Swift and C++ because neither ecosystem has
a central registry, Kotlin because its Maven Central publication has not
landed. Each page says exactly what the coordinate looks
like in the meantime.

## The same first call, everywhere

`GET /v1/models` is the catalogue of models the gateway currently serves. It is
a read, and it is one of the few routes that does not authenticate — the header
below is read only to annotate models your account has standing for, so the call
answers before you have a key. That makes it the honest first thing to run.

**curl**

```bash
curl https://api.hanzo.ai/v1/models \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**CLI**

```bash
hanzo models list
```

**TypeScript**

```typescript
import { AiApi, Configuration } from 'hanzoai'

const ai = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }))
const { data } = await ai.getModels()
```

**Python**

```python
import os
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
models = AiApi(client).get_models()
```

**Go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

models, _, err := client.ModelsAPI.AiListModels(context.Background()).Execute()
```

**Rust**

```rust
use hanzo_client::apis::{ai_api, configuration::Configuration};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let models = ai_api::get_models(&cfg).await?;
```

**Swift**

```swift
import Hanzo

let hanzo = HanzoAPIConfiguration(
    basePath: "https://api.hanzo.ai",
    customHeaders: ["Authorization": "Bearer \(key)"]
)

try await AiAPI.getModels(apiConfiguration: hanzo)
```

**Java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AiApi;
import ai.hanzo.cloud.model.AiModelList;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

AiModelList models = new AiApi(client).getModels();
```

> **Why Go spells the method differently**
>
> A client is a projection of the document at its own lock, and the locks move
> independently — so two clients can be cut from different releases of the same
> document and both be current. Go says `AiListModels`; the rest still say
> `getModels`. The [reference](https://docs.hanzo.ai/docs/openapi) prints the name per operation and
> says on the operation when a published client has not caught up, which is why it
> is the place to check rather than a page like this one.

## The hand-written TypeScript libraries

Three packages that are not generated, because what they offer is not in the
document: a shape, a grouping, and a browser flow.

| Package      | What it is                                                                                                                                                            |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@hanzo/ai`  | The AI client — `chat.completions`, `messages`, `models`, `agents`, `sandboxes`, `tools`, `sessions`. Takes `secretKey` on a server or `publishableKey` in a browser. |
| `@hanzo/sdk` | One typed client per service — IAM, KMS, Commerce, Billing, MPC, PaaS, Team — with subpath imports so a bundle carries only what it uses.                             |
| `@hanzo/iam` | [Identity](https://docs.hanzo.ai/docs/sdks/iam) — OIDC, JWT validation, browser PKCE, org switching, and React bindings.                                              |

Two more TypeScript packages are UI rather than API clients:
[`@hanzo/app`](https://docs.hanzo.ai/docs/sdks/app), the Hanzo app's window and workspace apps as
React components a host mounts, and [`@hanzo/mod`](https://docs.hanzo.ai/docs/sdks/mod), platform
look profiles, theme mods and web fonts for a page.

`@hanzo/ai` is the one to reach for when the job is inference or agents:

```typescript
import { Hanzo } from '@hanzo/ai'

const hanzo = new Hanzo({ secretKey: process.env.HANZO_API_KEY })

const answer = await hanzo.chat.completions.create({
  model: 'zen6',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
})
```

The key field is named for the key: an `sk-` goes in `secretKey` on a server, a
`pk-` goes in `publishableKey` in a browser, and the two are not
interchangeable. [Authentication](https://docs.hanzo.ai/docs/api-keys) is the whole rule.

## Product SDK Repositories & Runnable Examples

Hanzo's core AI models and agents maintain dedicated open-source repositories with runnable examples in Python, TypeScript, Go, Rust, and cURL, along with modular Rust recipe crates:

| Product                                            | Capability                             | GitHub Repository                                 | SDK Languages & Recipes                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------------------- | -------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **[Kai](https://docs.hanzo.ai/docs/decisions)**    | Calibrated probability decisions       | [`hanzoai/kai`](https://github.com/hanzoai/kai)   | [Python](https://github.com/hanzoai/kai/tree/main/examples/python) · [TypeScript](https://github.com/hanzoai/kai/tree/main/examples/typescript) · [Go](https://github.com/hanzoai/kai/tree/main/examples/go) · [Rust](https://github.com/hanzoai/kai/tree/main/examples/rust) · [20 Recipes](https://github.com/hanzoai/kai/tree/main/recipes)   |
| **[Zen](https://docs.hanzo.ai/docs/models/zen)**   | Foundation generative reasoning & code | [`hanzoai/zen`](https://github.com/hanzoai/zen)   | [Python](https://github.com/hanzoai/zen/tree/main/examples/cloud/client_cloud.py) · [Go](https://github.com/hanzoai/zen/tree/main/examples/cloud/client_cloud.go) · [Rust](https://github.com/hanzoai/zen/tree/main/examples/cloud/client_cloud.rs) · [Recipes](https://github.com/hanzoai/zen/tree/main/recipes)                                |
| **[Enso](https://docs.hanzo.ai/docs/models/enso)** | Learned microsecond model routing      | [`hanzoai/enso`](https://github.com/hanzoai/enso) | [Python](https://github.com/hanzoai/enso/tree/main/examples/python) · [Go](https://github.com/hanzoai/enso/tree/main/examples/go) · [Rust](https://github.com/hanzoai/enso/tree/main/examples/rust) · [Recipes](https://github.com/hanzoai/enso/tree/main/recipes)                                                                               |
| **[Kata](https://docs.hanzo.ai/docs/coding#kata)** | Autonomous test repair & CI/CD loop    | [`hanzoai/kata`](https://github.com/hanzoai/kata) | [Python](https://github.com/hanzoai/kata/tree/main/examples/python) · [TypeScript](https://github.com/hanzoai/kata/tree/main/examples/typescript) · [Go](https://github.com/hanzoai/kata/tree/main/examples/go) · [Rust](https://github.com/hanzoai/kata/tree/main/examples/rust) · [Recipes](https://github.com/hanzoai/kata/tree/main/recipes) |
| **[Gen](https://docs.hanzo.ai/docs/coding)**       | Agentic CLI harness & tool calling     | [`hanzoai/gen`](https://github.com/hanzoai/gen)   | [Python](https://github.com/hanzoai/gen/tree/main/examples/python) · [TypeScript](https://github.com/hanzoai/gen/tree/main/examples/typescript) · [Go](https://github.com/hanzoai/gen/tree/main/examples/go) · [Rust](https://github.com/hanzoai/gen/tree/main/examples/rust)                                                                    |
| **[Dev](https://docs.hanzo.ai/docs/dev)**          | Autonomous software engineer           | [`hanzoai/dev`](https://github.com/hanzoai/dev)   | Terminal, CLI, and cloud execution                                                                                                                                                                                                                                                                                                               |

## Where to go next

- **[Quickstart](https://docs.hanzo.ai/docs/quickstart)** — install, log in, and run the call above.
- **[Authentication](https://docs.hanzo.ai/docs/api-keys)** — the two key types and which one may
  ship in a browser.
- **[Reference](https://docs.hanzo.ai/docs/openapi)** — every operation, each shown as CLI, SDK, HTTP
  and MCP.
- **[CLI](https://docs.hanzo.ai/docs/cli)** — the same capabilities as command groups.