Agents - Chatbase

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). 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
`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

Paginated list of all AI agents for the account

Create AI agent

Create a new AI agent, optionally seeded with a URL

Get AI agent

Retrieve full AI agent details by ID

Update AI agent

Partial update of AI agent configuration

Update AI agent styles

Configure chat widget and center stage appearance

Train AI agent (deprecated)

No-op. Sources train on write.

Clone AI agent

Deep-copy an AI agent including all its sources

Toggle auto-resync

Re-sync websites, Notion pages, and tickets on a weekly schedule

Delete AI agent

Permanently delete an AI agent and all its data

Error codes

Agent-specific error codes beyond the standard authentication and rate-limiting errors:

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

​AI agent status

​Partial updates

​pendingSteps

​Training happens on write

​Endpoints