> ## 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, 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, and clone them for reuse. Training is not a separate step: sources train as soon as you write them (see the [Sources API](https://chatbase.co/docs/api-reference/v2/sources.md)). All endpoints are scoped to the account that owns the API key; a request for another account's AI agent returns 404, not 403, to avoid leaking existence.

## AI agent status

The `status` field on an AI agent is derived from its sources:

| Status | Meaning |
| - | - |
| `untrained` | No live sources yet |
| `training` | At least one source is still being processed |
| `failed` | A source failed to train; the others are live |
| `trained` | Every source is live |

To follow one source, poll `GET /agents/{agentId}/sources/{sourceId}`. To follow the whole AI agent, poll `GET /agents/{agentId}`.

## 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 AI 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](https://chatbase.co/docs/api-reference/v2/sources/create-source.md) |
| `TRAIN_AGENT` | Kept for compatibility. Sources train on write, so no action is needed. | None |

When `pendingSteps` is absent, all steps succeeded.

## Training happens on write

Each source trains on its own as soon as it is created, updated, or deleted. `POST /agents/{agentId}/train` is deprecated: it returns `200` with `deprecated: true` and a `Deprecation` header, and does nothing. Remove it from your integration and poll source `status` instead.

## Endpoints

> **[List AI agents](https://chatbase.co/docs/api-reference/v2/agents/list-agents.md)**
>
> Paginated list of all AI agents for the account

> **[Create AI agent](https://chatbase.co/docs/api-reference/v2/agents/create-agent.md)**
>
> Create a new AI agent, optionally seeded with a URL

> **[Get AI agent](https://chatbase.co/docs/api-reference/v2/agents/get-agent.md)**
>
> Retrieve full AI agent details by ID

> **[Update AI agent](https://chatbase.co/docs/api-reference/v2/agents/update-agent.md)**
>
> Partial update of AI agent configuration

> **[Update AI agent styles](https://chatbase.co/docs/api-reference/v2/agents/update-agent-styles.md)**
>
> Configure chat widget and center stage appearance

> **[Clone AI agent](https://chatbase.co/docs/api-reference/v2/agents/clone-agent.md)**
>
> Deep-copy an AI agent including all its sources

> **[Toggle auto-resync](https://chatbase.co/docs/api-reference/v2/agents/toggle-auto-retrain.md)**
>
> Re-sync websites, Notion pages, and tickets on a weekly schedule

> **[Delete AI agent](https://chatbase.co/docs/api-reference/v2/agents/delete-agent.md)**
>
> Permanently delete an AI agent and all its data

## Error codes

Agent-specific error codes beyond the standard [authentication and rate-limiting errors](https://chatbase.co/docs/api-reference/v2/error-handling.md):

<table>
  <thead>
    <tr>
      <th>Code</th>
      <th>HTTP</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>`AGENT_NOT_FOUND`</td><td>404</td><td>AI agent doesn't exist or doesn't belong to the authenticated account.</td></tr>
    <tr><td>`AGENT_NOT_TRAINED`</td><td>409</td><td>Auto-resync needs at least one live source. Add a source and wait for it to reach `trained`.</td></tr>
    <tr><td>`AGENT_LIMIT_REACHED`</td><td>403</td><td>The account has reached its plan's maximum number of AI agents. Delete an existing AI agent or upgrade your plan.</td></tr>
    <tr><td>`PLAN_FEATURE_NOT_AVAILABLE`</td><td>403</td><td>The requested feature is not available on the current plan. Upgrade to unlock it.</td></tr>
  </tbody>
</table>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.