SDKs

Install and authenticate the Python or TypeScript client. 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

# Organization API key — sessions, secrets, agents, traces, memories, models.
with Albus(
    api_key=os.environ["ALBUS_API_KEY"],
) as albus:
    print([session.id for session in albus.sessions.list_sessions().sessions])

# User bearer token — everything above, plus /tokens and /invites.
with Albus(
    access_token=os.environ["ALBUS_BEARER_AUTH"],
) as albus:
    print(albus.auth.whoami().user.email)

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

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

const { sessions } = await albus.sessions.listSessions();
console.log(sessions.map((session) => session.id));

The two clients spell it differently: Python takes the credential directly (api_key= or access_token=, and supplying both raises ValueError), while TypeScript takes a security object (apiKey or bearerAuth). Constructed with no credential, both read ALBUS_API_KEY and ALBUS_BEARER_AUTH from the environment — the same ALBUS_API_KEY the CLI reads, see Authentication. whoami() names whichever credential signed the request: user for a bearer token, api_key / apiKey for a key. The other is absent.

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 invocation key of a run:

response = albus.sessions.run_session(
    id="support-1234",
    user_prompt="summarize",
    agent_name="support-triage",
    agent={"model": {"name": "gemini-3.6-flash"}},
    invocation_key="support-1234-summary-1",
    wait_timeout_seconds=120,
)
key = response.headers["idempotency-key"][0]
reply = response.result.message.content

A run returns the one message it produced, in message — absent when the invocation has not answered yet. get_session / getSession returns the session’s history as messages. The key names an invocation in the SDKs (invocation_key=, invocationKey:) and travels as the HTTP Idempotency-Key header, which is why it is read back out of response.headers.

Traces, memories, and models

Beyond sessions, secrets, agents, and tokens, both clients expose the invocations Albus recorded, the memories agents wrote, and the models it serves:

traces = albus.traces.list_traces(agent_name="support-triage", limit=10)

trace = albus.traces.get_trace(invocation_key="support-1234-summary-1")
print(trace.result.status, len(trace.result.spans))
for attempt in trace.result.attempts or []:
    print(attempt.attempt, attempt.status, attempt.usage.total_tokens if attempt.usage else 0)

memories = albus.memories.list_memories(group="support")
albus.memories.delete_memory(group="support", id=memories.memories[0].id)

print([(model.name, model.provider) for model in albus.models.list_models().models])

const { traces } = await albus.traces.listTraces({ agentName: "support-triage" });
const trace = await albus.traces.getTrace({ invocationKey: "support-1234-summary-1" });

const { memories } = await albus.memories.listMemories({ group: "support" });
await albus.memories.deleteMemoryGroup({ group: "support" });

get_trace / getTrace pages spans with after and limit, returns only the latest attempt’s spans unless you pass attempts="all", and takes payloads=False for the shape of an invocation without its prompts and tool output — which raises the span limit to 500, so a whole trace usually fits in one request. See the API reference.

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 Errors. Retries are configured on the client (retry_config=), and run_session takes a retry_config= of its own to override it for that call. When configured, the retried statuses are 429, 500, 502, 503, and 504. Be careful combining that with a long-polling run: a 504 retry is a new request, so supply an invocation key or you will start a second invocation. No other per-request transport arguments exist — the timeout, base URL, and extra headers are client-level (timeout_ms=, server_url=, and the HTTP client you pass in).

Waiting for a reply

Both clients take the wait on the run itself, matching the API’s wait_timeout_seconds query parameter: wait_timeout_seconds=<n> in Python, and waitTimeoutSeconds: <n> beside body in TypeScript. Both default it to 1800 (30 minutes, the API’s maximum) and give run_session / runSession a matching 31-minute transport timeout, so a plain waiting run works without configuring anything.

const response = await albus.sessions.runSession({
  id: "support-1234",
  waitTimeoutSeconds: 120,
  body: {
    userPrompt: "summarize",
    agentName: "support-triage",
    agent: { model: { name: "gemini-3.6-flash" } },
  },
});

console.log(response.result.message?.content);

Pass 0 to return as soon as the invocation is accepted, then poll getSession / get_session until session.state leaves RUNNING.

A client-level timeout_ms / timeoutMs applies to the waiting run too, and replaces that 31-minute default. Set it above the longest wait you ask for, or the transport gives up while the run is still going.

Versions

SDKs are released after the API they document is deployed, never before. Current floors for the examples on this page:

Package	Version	Why
`albus-sdk`	0.8.0	`api_key=` / `access_token=` replaced the `security=` constructor argument, which now raises `TypeError`
`albus-sdk`	0.8.1	An omitted wait means 30 minutes rather than no wait, with a matching transport timeout
`albus-sdk`	0.11.0	`traces`, `memories`, and `models`; `invocation_key=` replaced `idempotency_key=`; a run returns `message`, not `messages`
`@albus-ts/sdk`	0.5.0	`waitTimeoutSeconds` — earlier versions cannot send the wait at all
`@albus-ts/sdk`	0.5.1	The same 30-minute default and transport timeout
`@albus-ts/sdk`	0.8.0	The same traces, memories, models, `invocationKey`, and `message` changes

Runtime requirements: Python 3.10+; for TypeScript, ECMAScript 2020+ — Node.js active or maintenance LTS (v18, v20), Bun 1+, or Deno 1.39+.

Getting started

Guides

Reference

API reference

Authentication

Responses

Traces, memories, and models

Errors

Waiting for a reply

Versions

​Authentication

​Responses

​Traces, memories, and models

​Errors

​Waiting for a reply

​Versions

Authentication

Responses

Traces, memories, and models

Errors

Waiting for a reply

Versions