Management Client

ApolloManagementClient is the server-side client for operating your workspace. It authenticates with your organization API key, sent as the x-organization-api-key header on every request — 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!,
});

The Apollo Agent Tester also covers this client — enter an organization API key on its Connect page to list projects, agents and versions, and to read conversations and their traces, from your browser.

All methods are async, fully typed, and throw typed errors on failure. Request and response models are exported under the Apollo namespace.

Projects

Method	Description
`projects.listProjects(request?)`	List the organization’s projects (paginated).
`projects.createProject(request)`	Create a project.
`projects.getProject(projectId)`	Fetch one project.
`projects.deleteProject(projectId)`	Delete a project.
`projects.getProjectUsage(projectId, request?)`	Usage aggregated across the project.

const project = await client.projects.createProject({ name: 'Support agents' });
const usage = await client.projects.getProjectUsage(project.id, {
  created_from: '2026-07-01T00:00:00Z',
});

Agents

Method	Description
`agents.listAgents(projectId, request?)`	List a project’s agents (paginated; optional `name` substring filter).
`agents.createAgent(projectId, request)`	Create an agent (optional `from_template`).
`agents.getAgent(agentId)`	Fetch one agent (includes `live_version_id`).
`agents.updateAgent(agentId, request)`	Rename an agent.
`agents.deleteAgent(agentId)`	Delete an agent and all its versions.
`agents.getAgentUsage(agentId, request?)`	Usage metrics for one agent.

const agent = await client.agents.createAgent(project.id, { name: 'Order support' });
await client.agents.updateAgent(agent.id, { name: 'Order & shipping support' });

Agent versions

Method	Description
`agentVersions.listVersions(agentId, request?)`	List versions (paginated, filterable by `status`/`tag`/`label`/`version_number`; `exclude_revisions` collapses revision history).
`agentVersions.createVersion(agentId, request)`	Create a draft (`source`: `agent-scope`, `template`, `version`, or `empty`).
`agentVersions.updateVersion(agentId, versionId, request)`	Update metadata (label, tags, notes).
`agentVersions.pushVersion(agentId, versionId, request)`	Push a configuration bundle (optional `commit_message`; `caller`: `agent_builder`, `ui`, or `cli`).
`agentVersions.pullVersion(agentId, versionId, request?)`	Download a configuration bundle (optional `version_tag`).
`agentVersions.publishVersion(agentId, versionId)`	Make the version live (ship or roll back).
`agentVersions.archiveVersion(agentId, versionId)`	Retire a version.

const draft = await client.agentVersions.createVersion(agent.id, { source: 'version', from_version: liveId });
await client.agentVersions.pushVersion(agent.id, draft.id, { caller: 'cli', bundle });
await client.agentVersions.publishVersion(agent.id, draft.id);

Threads

Method	Description
`threads.listThreads(request?)`	List the organization’s threads, newest first (paginated).
`threads.getThread(threadId, request?)`	Fetch one thread.
`threads.updateThread(threadId, request)`	Update a thread (currently `title`).
`threads.getThreadMessages(threadId, request?)`	The thread’s transcript.
`threads.getThreadTrace(threadId, request?)`	Every interaction’s reasoning trace (paginated). `trace.runtime` says which shape.
`threads.getInteractionTrace(interactionId, request?)`	One interaction’s reasoning trace — pass `{ thread_id }` for runtime v2 agents.

The trace methods are the management twins of the messaging ones — same shapes, same thread_id rule, authenticated with the organization API key instead of a publishable key:

const page = await client.threads.getThreadTrace(threadId, { 'page[size]': 20 });
const trace = await client.threads.getInteractionTrace(interactionId, { thread_id: threadId });
if (trace.runtime === 'v2') trace.citations_used;

Filter fields go directly on the request: project_id, agent_id, user_id, external_id, created (one value, or two for a range), tool, rule, and param. List endpoints also take sort_by / sort_order and page[size] / page[after] / page[before] for keyset pagination in either direction.

const page = await client.threads.listThreads({
  project_id: project.id,
  created: ['2026-07-01T00:00:00Z'],
  'page[size]': 20,
});

await client.threads.updateThread(threadId, { title: 'Renamed conversation' });

Prefer a filter such as project_id over an empty request — the unfiltered list sorts every thread in the organization and can be slow. For large windows, raise the per-call timeout: client.threads.listThreads({ project_id }, { timeoutInSeconds: 120 }).

Threads and runtime versions

A thread lives on the runtime that created it — reads and renames name that runtime with the runtime_version selector (e.g. '0.8.0', the runtime version the agent runs on; any value outside the 1.x family selects runtime v2, and it doesn’t have to match the thread’s exact build):

const thread = await client.threads.getThread(threadId, { runtime_version: '0.8.0' });
const transcript = await client.threads.getThreadMessages(threadId, { runtime_version: '0.8.0' });
await client.threads.updateThread(threadId, { runtime_version: '0.8.0', title: 'Renamed' });

Listing runtime v2 threads is always scoped to an agent or an end user, and only agent_id, user_id, and created (with agent_id) apply — the runtime v1–only filters return a clear 400 on the runtime v2 path:

const page = await client.threads.listThreads({
  runtime_version: '0.8.0',
  agent_id: [agentId],
});

Threads of runtime v1 agents (24-character hex ids) live on runtime v1, which is the default — the calls earlier on this page, without runtime_version, read those.

Pagination

List methods return a page: results plus meta cursors.

let page = await client.threads.listThreads({ project_id });

while (true) {
  for (const thread of page.results)
    console.log(thread.id, thread.title, thread.version_tag); // version_tag: the agent version the thread ran on
  if (!page.meta?.has_more) break;
  page = await client.threads.listThreads({
    project_id,
    'page[after]': page.meta.after_cursor!,
  });
}

Every method also accepts a final requestOptions argument (timeoutInSeconds, maxRetries, abortSignal, extra headers, extra queryParams, and a per-call organizationApiKey override) — see Best practices.

SDK

Runtime v1

Management Client

Projects

Agents

Agent versions

Threads

Threads and runtime versions

​Projects

​Agents

​Agent versions

​Threads

​Threads and runtime versions

​Pagination

Projects

Agents

Agent versions

Threads

Threads and runtime versions

Pagination