> ## Documentation Index
> Fetch the complete documentation index at: https://atlas-platform.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Atlas SDK

> Beta Python and TypeScript clients for Atlas chat sessions.

> [!WARNING]
>
> The Atlas SDK is in **beta**. Methods, payloads, and behavior may change as we work with your team.

The Atlas SDK is a typed client for Atlas chat. Create a session, send a message, and stream events until the run completes.

Python package: `arena-physica-atlas` (`atlas_sdk`). TypeScript package: `@arena-physica/atlas`. Your Arena Physica point of contact will get you set up.

## Get credentials

The default is **M2M**: a client ID and client secret. Ask your Arena Physica point of contact for credentials for your Atlas environment. You will be asked to provide the user groups those credentials can access.

Treat the client secret like a password. Keep it in server-side env or a secret store — not in git, and not in a browser or mobile app.

A Bearer token (`token` / `api_key`) is also supported. Do not set a token and M2M credentials together.

## Authenticate

| | Python | TypeScript | Env |
| - | - | - | - |
| Client ID | `client_id` | `clientId` | `ATLAS_CLIENT_ID` |
| Client secret | `client_secret` | `clientSecret` | `ATLAS_CLIENT_SECRET` |
| Token (optional) | `token` or `api_key` | `token` or `apiKey` | `ATLAS_TOKEN` |

If you omit constructor credentials, the SDK reads those env vars. Explicit arguments win over env.

M2M credentials are exchanged for an access token (`/desktop-config`, then Auth0 `client_credentials`). The client secret is never sent as a Bearer token.

## Create a client

`base_url` / `baseUrl` can be a host (`your-atlas-domain`) or a full URL. The SDK adds `https://` and `/api/v1` only when you omit them. Any other path is kept.

### Python

```python theme={null}
from atlas_sdk import Atlas

async def main() -> None:
    async with Atlas(
        base_url="https://your-atlas-domain",
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
    ) as atlas:
        session = await atlas.sessions.create()
        sent = await atlas.sessions.send_message(
            session_id=session.id,
            content="Why did this test fail?",
        )
        async for event in atlas.sessions.stream(
            session_id=session.id,
            message_id=sent.message_id,
        ):
            if event.type == "message.delta":
                print(event.delta, end="", flush=True)
```

### TypeScript

```typescript theme={null}
import { Atlas } from '@arena-physica/atlas'

const atlas = new Atlas({
  baseUrl: 'https://your-atlas-domain',
  clientId: process.env.ATLAS_CLIENT_ID,
  clientSecret: process.env.ATLAS_CLIENT_SECRET,
})

const session = await atlas.sessions.create()
const sent = await atlas.sessions.sendMessage({
  sessionId: session.id,
  content: 'Why did this test fail?',
})

for await (const event of atlas.sessions.stream({
  sessionId: session.id,
  messageId: sent.messageId,
})) {
  if (event.type === 'message.delta') {
    process.stdout.write(event.delta)
  }
}
```

`send_message` / `sendMessage` returns immediately with a `message_id`. Completion arrives on the stream as `run.completed` or `run.failed`.

### Bearer token

Use this instead of M2M when you already have a user access token. Do not pass `token` / `apiKey` together with `client_id` / `clientId`.

```python theme={null}
async with Atlas(
    base_url="https://your-atlas-domain",
    api_key="YOUR_TOKEN",
) as atlas:
    ...
```

```typescript theme={null}
const atlas = new Atlas({
  baseUrl: 'https://your-atlas-domain',
  apiKey: process.env.ATLAS_TOKEN,
})
```

## Operations

Python uses `snake_case`. TypeScript uses `camelCase`.

| Python | TypeScript | HTTP | Path | Purpose |
| - | - | - | - | - |
| `sessions.create` | `sessions.create` | `POST` | `/chat/v2/sessions` | Start a chat session |
| `sessions.send_message` | `sessions.sendMessage` | `POST` | `/chat/v2/sessions/{session_id}/messages` | Send a message and get `message_id` |
| `sessions.stream` | `sessions.stream` | `GET` | `/chat/v2/sessions/{session_id}/messages/{message_id}/events` | Stream events for that message |

`create` takes no arguments. `send_message` / `sendMessage` takes the message text.

## Events

Every event includes `session_id` and `message_id`.

| Type | Extra fields | When |
| - | - | - |
| `run.started` | | The turn begins |
| `message.started` | | Assistant text is about to stream |
| `message.delta` | `delta` | Incremental assistant text |
| `reasoning.delta` | `delta` | Incremental reasoning text |
| `tool.started` | `tool_id`, `name` | A tool call starts |
| `tool.completed` | `tool_id`, `error` | A tool call finishes |
| `message.completed` | `content` | Full assistant text |
| `run.completed` | | The turn succeeded |
| `run.failed` | `error` | The turn failed |

Ignore unknown event types so later additions do not break your client.

## Env-only configuration

```bash theme={null}
export ATLAS_CLIENT_ID="..."
export ATLAS_CLIENT_SECRET="..."
# or a user token
export ATLAS_TOKEN="..."
```

```python theme={null}
async with Atlas(base_url="your-atlas-domain") as atlas:
    ...
```

```typescript theme={null}
const atlas = new Atlas({ baseUrl: 'your-atlas-domain' })
```

## Errors

Missing or mixed credentials raise `AtlasAuthError` (token and M2M together, or only one of client id / secret).

HTTP failures raise from the underlying client (`httpx` in Python; `Error` in TypeScript).

## Related

* [Authentication and Configuration](https://atlas-platform.mintlify.site/platform_2/auth-config.md)
* [Agentic API](https://atlas-platform.mintlify.site/platform_2/api.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.