SDK - AUI

TypeScript@aui.io/aui-clientv3

The official TypeScript/JavaScript SDK wraps the Apollo API 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

npm install @aui.io/aui-client

yarn add @aui.io/aui-client

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.

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.

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, {});

Agent runtimes: v1 and v2

Every agent runs on one of two runtime generations — v1 (the classic runtime) or v2 (the current, streaming-first generation). You never pick one when sending: sendMessage, streamMessage, rerun, and the channel openers route automatically based on the agent behind your key. The differences surface in a few places only:

Capability	v1 agents	v2 agents
Send / stream / rerun / channels	✅	✅
Reading threads back	Works with no extra field	Pass `runtime_version` (e.g. `'0.8.0'`)
WebSocket session	✅	❌ — use `streamMessage` (SSE) instead
Traces	✅	Not yet available
Thread id format	24-character hex	UUID

The rule to remember: a thread lives on the runtime that created it — reading a v2 thread without runtime_version asks the wrong runtime and returns 404. Pass the runtime version your agent runs on (e.g. '0.8.0'); any value outside the 1.x family selects v2, and it doesn’t have to match the thread’s exact build. Not sure which kind of agent you have? Check a thread id it produces: UUIDs mean v2.

Why use the SDK?

Auth handled for you

Token exchange, refresh, and header injection are automatic — construct the client with a key and start calling.

Type safety

Full TypeScript definitions with IntelliSense across every method and payload, exported under the Apollo namespace.

WebSocket management

connect() returns a reconnecting socket with typed envelopes and resume support.

Typed errors

ApolloError, ApolloTimeoutError, and per-status classes like Apollo.NotFoundError for clean handling.

Automatic retries

Transient failures retry automatically (2 attempts by default, tunable per call).

Always in sync

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:

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:

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

Messaging client

Send and stream messages, read conversations, and reach users on WhatsApp/SMS.

Management client

Operate projects, agents, versions, threads, and usage from your backend.

WebSocket

Real-time sessions with typed envelopes, reconnection, and resume.

Best practices

Error handling, timeouts, retries, and key hygiene.

API

The underlying REST + WebSocket API the SDK wraps.

​Installation

​Quick start — messaging

​Quick start — management

​Agent runtimes: v1 and v2

​Why use the SDK?