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

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

​Why use the SDK?