> ## Documentation Index
> Fetch the complete documentation index at: https://docs.albus.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> The Python and TypeScript clients — installation, authentication, and what they generate from.

Both SDKs are generated from the same [OpenAPI
contract](https://docs.albus.sh/openapi/openapi.yaml) that produces the [API
reference](/reference/overview), so every operation, field, and error there
exists in both, with the same semantics.

|              | Python                                                                | TypeScript                                                                    |
| ------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Package      | [`albus-sdk`](https://pypi.org/project/albus-sdk/)                    | [`@albus-ts/sdk`](https://www.npmjs.com/package/@albus-ts/sdk)                |
| Install      | `pip install albus-sdk`                                               | `npm install @albus-ts/sdk`                                                   |
| Source       | [albusgroup/albus-python](https://github.com/albusgroup/albus-python) | [albusgroup/albus-typescript](https://github.com/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

<CodeGroup>
  ```python Python theme={null}
  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:
      ...
  ```

  ```typescript TypeScript theme={null}
  import { Albus } from "@albus-ts/sdk";

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

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](/getting-started/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:

```python theme={null}
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](/guides/run-a-session#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](/guides/releases). SDKs are released after the API they
document is deployed, never before.