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

# Agents

> Create and manage agents inside your projects.

An **agent** is a deployed conversational AI, owned by a
[project](/api/management/projects). What the agent actually does is defined
by its [versions](/api/management/versions) — exactly one version is live at a
time, referenced by the agent's `live_version_id`.

***

## Create an agent

```bash cURL theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/management/v1/projects/{projectId}/agents" \
  -H "Content-Type: application/json" \
  -H "x-organization-api-key: <org_api_key>" \
  -d '{ "name": "Order support" }'
```

### POST `/management/v1/projects/{projectId}/agents`

<ParamField body="name" type="string" required>
  Agent name — 2 to 50 characters, and not only whitespace.
</ParamField>

New agents start without a live version — create and
[publish a version](/api/management/versions) to make the agent answer.

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "id": "6a344d186d3160971ec62eb6",
    "project_id": "5f2b8c1a9d4e3f0012ab34cd",
    "name": "Order support",
    "live_version_id": null,
    "created_at": "2026-07-13T14:02:11Z",
    "updated_at": "2026-07-13T14:02:11Z"
  }
  ```
</ResponseExample>

***

## List agents

### GET `/management/v1/projects/{projectId}/agents`

Lists the project's agents as a [paginated
list](/api/management/projects#pagination).

<ParamField query="name" type="string">
  Case-insensitive substring match on the agent name.
</ParamField>

## Get an agent

### GET `/management/v1/agents/{agentId}`

Returns one agent, including which version is currently live
(`live_version_id`).

## Rename an agent

### PATCH `/management/v1/agents/{agentId}`

<ParamField body="name" type="string">
  The new agent name — 2 to 50 characters, and not only whitespace.
</ParamField>

Renaming is the only update here — to change which version is live,
[publish a version](/api/management/versions#publish-a-version) instead.

## Delete an agent

### DELETE `/management/v1/agents/{agentId}`

Deletes the agent **and all of its versions**. This cannot be undone. Returns
`204`.

## Agent usage

### GET `/management/v1/agents/{agentId}/usage`

Usage metrics for this agent — see [Usage](/api/management/usage).