Skip to main content
TypeScript@aui.io/aui-clientv3
The official TypeScript/JavaScript SDK wraps the Apollo API with full type definitions, automatic authentication, retries, and built-in streaming. It exposes two clients, one per credential — import the one that matches where your code runs:

Try it without writing code

Apollo Agent Tester

Every SDK feature in a browser page: paste a publishable key (and optionally an organization API key), connect, and send messages, stream replies, read conversations back, inspect reasoning traces, and manage projects, agents and versions. Each panel shows the SDK call it makes, so what you click is what you write.
The tester runs entirely in your browser against the production API — the same calls this SDK makes, with the ids from one step carried into the next. It is the quickest way to see what your agent returns before you integrate.

Installation

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.

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.

Threads and runtime versions

A thread lives on the runtime that created it, and thread reads name that runtime. Sending never does — sendMessage, streamMessage, rerun, and the channel openers resolve the runtime from the agent behind your key. When you read a thread back (listMessages, and the management getThread, getThreadMessages, updateThread, listThreads), pass the runtime version your agent runs on as runtime_version:
The rule is on the major version: any value outside the 1.x family selects runtime v2, so it doesn’t have to match the thread’s exact build. Omitting it asks runtime v1 instead — a runtime v2 thread read that way returns 404.
Runtime v1 agents — as a rule of thumb, agents created before August 1 2026 — take no runtime_version on reads, keep WebSocket sessions, return the typed runtime v1 trace, and produce 24-character hex thread ids (runtime v2 ids are UUIDs). Everything runtime-v1-specific is collected in Runtime v1 agents.

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.

Streaming built in

streamMessage returns the reply as an async-iterable SSE stream — token deltas, the final message, follow-up suggestions — resumable with Last-Event-ID.

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:
To point at a different host (e.g. a regional deployment), pass baseUrl:
The known base URLs are exported as ApolloEnvironment, and both clients accept a logging option (the logging namespace is exported too) for request-level logs.

Resolved key context

After the first request (or an explicit getContext() call), the messaging client exposes the scope resolved from your publishable key:

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.

Best practices

Error handling, timeouts, retries, streaming resilience, and key hygiene.

Runtime v1 agents

On an agent created before August 1 2026? What differs, and the WebSocket session those agents still support.

API

The underlying REST + SSE API the SDK wraps.

Apollo Agent Tester

Try every SDK call from your browser with your own keys — no code needed.