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

# Agents

> Programmatically create, configure, train, and manage your Chatbase AI agents.

The Agents API gives you full programmatic control over your AI agents — create them, configure their behavior and widget styles, manage training, and clone them for reuse. All endpoints are scoped to the account that owns the API key; a request for another account's agent returns 404, not 403, to avoid leaking existence.

## Agent status

The `status` field on an agent reflects where it is in its training lifecycle:

| Status      | Meaning                                                    |
| ----------- | ---------------------------------------------------------- |
| `untrained` | Agent has never been trained                               |
| `training`  | A training run is in progress                              |
| `trained`   | Training completed; agent is using its latest sources      |
| `updated`   | Sources changed since the last training — retrain to apply |

Use `GET /agents/{agentId}` to poll `status` after triggering a train or after creating an agent with a URL.

## Partial updates

`PUT /agents/{agentId}` uses **partial update semantics** — only the fields you include are changed.

| What you send                      | Result                                         |
| ---------------------------------- | ---------------------------------------------- |
| Omit a field                       | No change — field keeps its current value      |
| Send a value                       | Field is updated to that value                 |
| Send `null` (nullable fields only) | Feature is disabled or field resets to default |

Example: `{ "voiceSettings": null }` disables voice mode. An empty body `{}` makes no changes.

The `ipRateLimits` object also supports partial updates within itself — send only the sub-fields you want to change without affecting the others.

## `pendingSteps`

Create and clone both return a 201 even when secondary steps fail. The agent always exists — `id` is always in the response. `pendingSteps` tells you what to retry:

| Step          | Meaning                                  | Recovery                                                                  |
| ------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| `ADD_SOURCE`  | The `url` could not be added as a source | Add sources manually via the [Sources API](/docs/api-v2/sources/create-source) |
| `TRAIN_AGENT` | Training could not be started            | Trigger manually via [Train agent](/docs/api-v2/agents/train-agent)            |

When `pendingSteps` is absent, all steps succeeded.

## Training is asynchronous

`POST /agents/{agentId}/train` queues a job and returns immediately. Poll `GET /agents/{agentId}` and watch `status` to track progress. If training is already running you'll get `409 AGENT_ALREADY_TRAINING` — wait for the current run to finish rather than retrying.

## Endpoints

<CardGroup cols={2}>
  <Card title="List agents" icon="list" href="/docs/api-v2/agents/list-agents">
    Paginated list of all agents for the account
  </Card>

  <Card title="Create agent" icon="plus" href="/docs/api-v2/agents/create-agent">
    Create a new agent, optionally seeded with a URL
  </Card>

  <Card title="Get agent" icon="magnifying-glass" href="/docs/api-v2/agents/get-agent">
    Retrieve full agent details by ID
  </Card>

  <Card title="Update agent" icon="pen" href="/docs/api-v2/agents/update-agent">
    Partial update of agent configuration
  </Card>

  <Card title="Update agent styles" icon="palette" href="/docs/api-v2/agents/update-agent-styles">
    Configure chat widget and center stage appearance
  </Card>

  <Card title="Train agent" icon="brain" href="/docs/api-v2/agents/train-agent">
    Trigger a training run on current sources
  </Card>

  <Card title="Clone agent" icon="copy" href="/docs/api-v2/agents/clone-agent">
    Deep-copy an agent including all its sources
  </Card>

  <Card title="Toggle auto-retrain" icon="rotate" href="/docs/api-v2/agents/toggle-auto-retrain">
    Enable or disable 7-day automatic retraining
  </Card>

  <Card title="Delete agent" icon="trash" href="/docs/api-v2/agents/delete-agent">
    Permanently delete an agent and all its data
  </Card>
</CardGroup>

## Error codes

Agent-specific error codes beyond the standard [authentication and rate-limiting errors](/docs/api-v2/error-handling):

<table>
  <thead>
    <tr>
      <th style={{ whiteSpace: 'nowrap' }}>Code</th>
      <th>HTTP</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>AGENT\_NOT\_FOUND</code></td><td>404</td><td>Agent doesn't exist or doesn't belong to the authenticated account.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>AGENT\_ALREADY\_TRAINING</code></td><td>409</td><td>A training run is already in progress. Wait for it to complete before starting another.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>AGENT\_NOT\_TRAINED</code></td><td>409</td><td>Auto-retrain requires the agent to have been trained at least once. <a href="/docs/api-v2/agents/train-agent">Train the agent</a> first.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>AGENT\_LIMIT\_REACHED</code></td><td>403</td><td>The account has reached its plan's maximum number of agents. Delete an existing agent or upgrade your plan.</td></tr>
    <tr><td style={{ whiteSpace: 'nowrap' }}><code>PLAN\_FEATURE\_NOT\_AVAILABLE</code></td><td>403</td><td>The requested feature is not available on the current plan. Upgrade to unlock it.</td></tr>
  </tbody>
</table>