Management Client

Operate projects, agents, versions, threads, and usage — server-side, with your organization API key.

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, { filters })	List a project’s agents (paginated).
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, { filters })	List versions (paginated, filterable by status/tag/label).
agentVersions.createVersion(agentId, request)	Create a draft (source: empty, 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({ filters })	List the organization’s threads, newest first (paginated).
threads.getThread(threadId)	Fetch one thread.
threads.updateThread(threadId, request)	Update a thread (currently title).
threads.getThreadMessages(threadId)	The thread’s transcript.
threads.getThreadTrace(threadId)	Every interaction’s reasoning trace.
threads.getInteractionTrace(interactionId)	One interaction’s reasoning trace.

filters supports 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({
  filters: { 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 filters object — the unfiltered list sorts every thread in the organization and can be slow. For large windows, raise the per-call timeout: client.threads.listThreads({ filters }, { timeoutInSeconds: 120 }).

Pagination

List methods return a page: results plus meta cursors.

let page = await client.threads.listThreads({ filters: { 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({
    filters: { project_id },
    'page[after]': page.meta.after_cursor!,
  });
}

Every method also accepts a final requestOptions argument (timeoutInSeconds, maxRetries, abortSignal, extra headers) — see Best practices.