Skip to content
Brokkr

SDKs

Brokkr ships generated client SDKs for Rust, Python, and TypeScript. All three are produced from the same OpenAPI spec (openapi/brokkr-v1.json) and share the same shape:

  • Single-credential constructor — pass a PAK; the wrapper handles auth headers.
  • Access the raw generated API surface via .api / .api() when the wrapper doesn’t cover what you need.
  • Opt-in retry helper with exponential backoff for transient failures.
  • Typed errors with a stable code field for pattern matching.
  • Folder-of-manifests helpers — submit_manifests/apply (submitManifests/apply in TS) take a directory or file, validate each document, and submit it as a stack’s desired state; apply is idempotent (re-submits only when the bundle changed).

Getting started

Section titled “Getting started”
Language Install Import
Rust cargo add brokkr-client use brokkr_client::BrokkrClient;
Python pip install brokkr-client from brokkr import BrokkrClient
TypeScript npm install @colliery-io/brokkr-client import { BrokkrClient } from "@colliery-io/brokkr-client";

Construct the client with the broker URL and one PAK. The base URL can be the broker root (https://broker.example.com) or end in /api/v1. The client adds /api/v1 when it is absent and never adds it twice. The brokkr CLI uses the same rule. To create stacks and apply manifests, use a generator PAK (see Authentication).

Detailed walkthroughs:

  • Rust — brokkr-client crate, includes a worked agent example.
  • Python — brokkr-client distribution (wraps the low-level brokkr-client-generated, pulled in transitively).
  • TypeScript — @colliery-io/brokkr-client package. Types are generated via openapi-typescript; the runtime is openapi-fetch.

Versioning and compatibility

Section titled “Versioning and compatibility”

The SDK version matches the broker version. The git tag vX.Y.Z drives the version stamped into the broker container images, helm charts, and all three SDKs in the same release. Use the SDK release that has the same version as your broker. Mixing versions is not supported. See the releases page.

There is no separate SDK-only release cadence. If the broker API changes, the SDKs are regenerated and republished in the same tag.

Authentication

Section titled “Authentication”

Every Brokkr SDK uses a single credential: a PAK (Prefixed API Key), attached to the Authorization header of every request. The Python and TypeScript wrappers send it as Authorization: Bearer <pak>; the Rust wrapper sends the bare token with no Bearer prefix. The broker accepts either, so this only matters if you are reading a packet capture or writing your own client.

The OpenAPI spec declares three security schemes — admin_pak, agent_pak, generator_pak — but they all map to the same header. All PAKs share one format (by default brokkr_BR<short>_<long>); the role is not encoded in the token. The broker resolves the role at runtime by hashing the PAK and looking it up against the admin role, agents, and generators tables (POST /api/v1/auth/pak tells you which identity a PAK resolves to):

Role What it can do
Admin Full API surface; create/rotate other PAKs
Agent Heartbeat, fetch target state, report health and events
Generator Create/update stacks and deployment objects

Where PAKs come from:

  • Admin — minted offline with brokkr-broker generate-pak, whose hash you set as broker.pak_hash before the first broker startup. If you do not set pak_hash, the broker uses the embedded default hash, and the matching public development PAK is the admin PAK. Only an explicit empty pak_hash makes the broker generate a PAK at first startup and write it to /tmp/brokkr-keys/key.txt inside the broker container (see Managing PAKs).
  • Agent — returned once when an agent is created (POST /api/v1/agents); rotate with POST /api/v1/agents/{id}/rotate-pak, which returns the new PAK once.
  • Generator — returned once when a generator is created (POST /api/v1/generators); rotate with POST /api/v1/generators/{id}/rotate-pak, which returns the new PAK once.

Both the REST rotation endpoints and the brokkr-broker rotate agent/generator CLI commands print the new PAK once; the REST endpoints additionally invalidate the broker’s auth cache immediately.

POST /api/v1/auth/pak also returns a readonly flag alongside admin, agent, and generator. It is false for every PAK you provision through the API or CLI — it marks the broker’s own ephemeral console credential, a fourth in-memory credential class that the Operator Console mints per process and that may only issue reads. You will not construct an SDK client with one, but do not assume the field is absent when introspecting.

Error handling

Section titled “Error handling”

Every documented 4xx/5xx response returns a typed ErrorResponse:

{ "code": "agent_not_found", "message": "...", "details": { ... } }

Pattern-match on code — it is stable across versions. The message is human-readable and may change. See the stable error codes table for what to expect.

Pagination

Section titled “Pagination”

The v1 API returns full collections without cursor tokens, so no SDK exposes pagination iterators. If pagination is added later, the wrappers will grow Stream adapters; consumers won’t need to change call sites.

Keeping SDKs in sync with the broker

Section titled “Keeping SDKs in sync with the broker”

If you change the broker’s API surface, regenerate the spec and SDKs. See Regenerating SDKs.