> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts theme={"dark"}
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](/sdk/best-practices#error-handling) 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.          |

```ts theme={"dark"}
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.                  |

```ts theme={"dark"}
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.                                             |

```ts theme={"dark"}
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`.

```ts theme={"dark"}
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' });
```

<Tip>
  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 })`.
</Tip>

## Pagination

List methods return a page: `results` plus `meta` cursors.

```ts theme={"dark"}
let page = await client.threads.listThreads({ filters: { project_id } });

while (true) {
  for (const thread of page.results) console.log(thread.id, thread.title);
  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](/sdk/best-practices#timeouts-and-retries).