> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.
# SDK
> The official TypeScript/JavaScript SDK for the Apollo API — two type-safe clients, one per credential.
TypeScript
@aui.io/aui-client
v3
The official TypeScript/JavaScript SDK wraps the [Apollo API](/api/overview)
with full type definitions, automatic authentication, retries, and built-in
WebSocket handling. It exposes **two clients, one per credential** — import the
one that matches where your code runs:
| Client | Credential | Browser-safe | Surface |
| ------------------------ | ---------------------------------- | -------------------- | ------------------------------------------------ |
| `ApolloMessagingClient` | Publishable key (`pk_network_...`) | Yes | End-user messaging, channels, WebSocket sessions |
| `ApolloManagementClient` | Organization API key | **No — server only** | Projects, agents, versions, threads, usage |
## Installation
```bash npm theme={"dark"}
npm install @aui.io/aui-client
```
```bash yarn theme={"dark"}
yarn add @aui.io/aui-client
```
```bash pnpm theme={"dark"}
pnpm add @aui.io/aui-client
```
Requires Node.js ≥ 18 (or any modern browser for the messaging client). Type
definitions ship with the package.
## Quick start — messaging
The messaging client authenticates with your publishable key. It exchanges the
key for a short-lived access token and refreshes it as needed — you never
handle tokens directly, and the agent is derived from the key rather than
passed in request bodies.
```ts theme={"dark"}
import { ApolloMessagingClient } from '@aui.io/aui-client';
const client = new ApolloMessagingClient({
publishableKey: 'pk_network_xxxxxxxxxxxxxxxxxxxxxxxx',
});
// Send a message — a conversation thread is created automatically
const response = await client.messaging.sendMessage({
user_id: 'end-user-123',
text: 'What can you help me with?',
});
console.log(response.thread_id); // pass this back to continue the thread
console.log(response.message.text);
```
## Quick start — management
The management client authenticates with your organization API key, sent as
the `x-organization-api-key` header on every request. It's meant for backend
services and CI — never expose the key in the browser.
```ts theme={"dark"}
import { ApolloManagementClient } from '@aui.io/aui-client';
const client = new ApolloManagementClient({
organizationApiKey: process.env.AUI_ORG_API_KEY!,
});
const projects = await client.projects.listProjects();
const agents = await client.agents.listAgents(projects.results[0].id, { filters: {} });
```
## Why use the SDK?
Token exchange, refresh, and header injection are automatic — construct the
client with a key and start calling.
Full TypeScript definitions with IntelliSense across every method and
payload, exported under the `Apollo` namespace.
`connect()` returns a reconnecting socket with typed envelopes and resume
support.
`ApolloError`, `ApolloTimeoutError`, and per-status classes like
`Apollo.NotFoundError` for clean handling.
Transient failures retry automatically (2 attempts by default, tunable per
call).
Generated from the live API specification, so the client tracks the API as
it evolves.
## Environment
Both clients default to production — no configuration needed:
```
https://api-v3.aui.io/apollo-api
```
To point at a different host (e.g. a regional deployment), pass `baseUrl`:
```ts theme={"dark"}
const client = new ApolloMessagingClient({
publishableKey: 'pk_network_...',
baseUrl: 'https://api-eu-v3.aui.io/apollo-api',
});
```
## Resolved key context
After the first request (or an explicit `getContext()` call), the messaging
client exposes the scope resolved from your publishable key:
```ts theme={"dark"}
const context = await client.getContext();
context.agentId; // the agent your calls run against
context.organizationId; // the organization the key belongs to
context.keyType; // 'agent' | 'unknown'
```
## Explore the SDK
Send and stream messages, read conversations, and reach users on
WhatsApp/SMS.
Operate projects, agents, versions, threads, and usage from your backend.
Real-time sessions with typed envelopes, reconnection, and resume.
Error handling, timeouts, retries, and key hygiene.
The underlying REST + WebSocket API the SDK wraps.