# Swift

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

> The Hanzo package for SwiftPM — async/await, no dependencies, one class per capability. Builds on Apple platforms and Linux.

The Swift client is generated from the API's own document and has no external
dependencies — `URLSession`, `Codable`, `async/await`, nothing else. It builds
on Apple platforms and on Linux.

## Install

Swift Package Manager, from the repository:

```swift
// Package.swift
dependencies: [
    .package(url: "https://github.com/hanzo-swift/sdk", from: "8.0.0")
]
```

```swift
.target(name: "App", dependencies: [.product(name: "Hanzo", package: "sdk")])
```

In Xcode: \*_File → Add Package Dependencies…_\* → `https://github.com/hanzo-swift/sdk`.

The package declares `swiftLanguageModes: [.v6]`, so Swift 6 is required: the
client throws typed errors (`async throws(ErrorResponse)`), which earlier
language modes do not parse.

## The shape

A configuration value and one class per capability:

```swift
import Hanzo

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

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

`HanzoAPIConfiguration.shared` is the default every call falls back to, so a
program serving one tenant sets it once instead of passing it. `basePath`
already defaults to `https://api.hanzo.ai`.

Method names are the document's operation ids, and a path parameter reads as
`by`: `GET /v1/billing/balance` is `getBillingBalance`, and `GET /v1/kv/{name}`
is `getKvByName(name:)`. Request and response types live under
`Sources/Hanzo/Models`.

> **Reading a body the document does not describe**
>
> A few routes — `getModels` among them — state their address without stating
> their response shape, so the generated method returns nothing to decode. Call
> `getModelsWithRequestBuilder(...).execute()` and read the response directly when
> you need the body.

## Auth

One scheme: a bearer token in `Authorization`. That is an IAM access token or a
Hanzo API key — `sk-` on a server, `pk-` in an app you ship. See
[Authentication](https://docs.hanzo.ai/docs/api-keys). Every operation sends it except the four that
do not authenticate: `getModels`, `getModelsProviders`, `getCommands` and
`getOpenapiJson`.

## Resources

- Source — [hanzo-swift/sdk](https://github.com/hanzo-swift/sdk)
- [Every `/v1` operation →](https://docs.hanzo.ai/docs/openapi)