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

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.
`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`).
`agentVersions.createVersion(agentId, request)`	Create a draft (`source`: `agent-scope`, `template`, or `version`).
`agentVersions.updateVersion(agentId, versionId, request)`	Update metadata (label, tags, notes).
`agentVersions.pushVersion(agentId, versionId, request)`	Push a configuration bundle.
`agentVersions.pullVersion(agentId, versionId, request?)`	Download a configuration bundle.
`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)`	Every interaction’s reasoning trace (v1 threads only).
`threads.getInteractionTrace(interactionId)`	One interaction’s reasoning trace (v1 threads only).

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.

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 }).

v2 threads

Threads created by agents on the v2 runtime (UUID thread ids) live on that runtime — reads and renames take the runtime_version selector (e.g. '0.8.0', the runtime version the agent runs on):

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 v2 threads is always scoped to an agent or an end user, and only agent_id, user_id, and created (with agent_id) apply — v1-specific filters return a clear 400 on the v2 path:

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

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) — see Best practices.

​Projects

​Agents

​Agent versions

​Threads

​v2 threads

​Pagination

Projects

Agents

Agent versions

Threads

v2 threads

Pagination