Agents - Chatbase

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
`TRAIN_AGENT`	Training could not be started	Trigger manually via 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

List agents

Paginated list of all agents for the account

Create agent

Create a new agent, optionally seeded with a URL

Get agent

Retrieve full agent details by ID

Update agent

Partial update of agent configuration

Update agent styles

Configure chat widget and center stage appearance

Train agent

Trigger a training run on current sources

Clone agent

Deep-copy an agent including all its sources

Toggle auto-retrain

Enable or disable 7-day automatic retraining

Delete agent

Permanently delete an 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	Agent doesn’t exist or doesn’t belong to the authenticated account.
`AGENT_ALREADY_TRAINING`	409	A training run is already in progress. Wait for it to complete before starting another.
`AGENT_NOT_TRAINED`	409	Auto-retrain requires the agent to have been trained at least once. Train the agent first.
`AGENT_LIMIT_REACHED`	403	The account has reached its plan’s maximum number of agents. Delete an existing agent or upgrade your plan.
`PLAN_FEATURE_NOT_AVAILABLE`	403	The requested feature is not available on the current plan. Upgrade to unlock it.

​Agent status

​Partial updates

​pendingSteps

​Training is asynchronous

​Endpoints