SDKs

Both SDKs are generated from the same OpenAPI contract that produces the API reference, so every operation, field, and error there exists in both, with the same semantics.

	Python	TypeScript
Package	`albus-sdk`	`@albus-ts/sdk`
Install	`pip install albus-sdk`	`npm install @albus-ts/sdk`
Source	albusgroup/albus-python	albusgroup/albus-typescript
Sync client	`Albus`	`Albus`
Async client	`AsyncAlbus` (same method names, awaited)	native
Base URL	`https://albus.sh/api`	`https://albus.sh/api`

Method names follow the operation ids: sessions.run_session / sessions.runSession, secrets.create_secret / secrets.createSecret, and so on.

Authentication

import os
from albus_sdk import Albus, models

# Organization API key — sessions, secrets, agents.
with Albus(
    security=models.Security(api_key_auth=os.environ["ALBUS_API_KEY_AUTH"]),
) as albus:
    ...

# User bearer token — /whoami and /tokens.
with Albus(
    security=models.Security(bearer_auth=os.environ["ALBUS_BEARER_AUTH"]),
) as albus:
    ...

import { Albus } from "@albus-ts/sdk";

const albus = new Albus({
  security: { apiKeyAuth: process.env.ALBUS_API_KEY_AUTH ?? "" },
});

Constructed with no security argument, both clients read ALBUS_API_KEY_AUTH and ALBUS_BEARER_AUTH from the environment. Note these are not the CLI’s ALBUS_API_KEY — see Authenticate.

Responses

An operation with response headers you need returns them alongside the body: response.result is the parsed body and response.headers the headers. That is how you read the effective idempotency key of a run:

response = albus.sessions.run_session(...)
key = response.headers["idempotency-key"][0]
reply = response.result.messages[-1].content

Errors

Every non-2xx status raises a typed error carrying status_code, message, and body (errors.AlbusError and its subclasses in Python). Handle at least 423, 429, and 504 — see failure modes. Both SDKs retry 429, 500, 502, 503, and 504 when you pass a retry config. Be careful combining that with a long-polling run: a 504 retry is a new request, so supply an idempotency key or you will start a second invocation.

Versions

The published SDK version that matches the current API reference is recorded in the release policy. SDKs are released after the API they document is deployed, never before.

Getting started

Guides

For coding agents

Alpha

Reference

API reference

Authentication

Responses

Errors

Versions

​Authentication

​Responses

​Errors

​Versions

Authentication

Responses

Errors

Versions