Skip to main content
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 agent returns 404, not 403, to avoid leaking existence.

​
Agent status

The status field on an agent is derived from its sources: To follow one source, poll GET /agents/{agentId}/sources/{sourceId}. To follow the whole agent, poll GET /agents/{agentId}.

​
Partial updates

PUT /agents/{agentId} uses partial update semantics — only the fields you include are changed. 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: 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 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 (deprecated)

No-op. Sources train on write.

Clone agent

Deep-copy an agent including all its sources

Toggle auto-resync

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

Delete agent

Permanently delete an agent and all its data

​
Error codes

Agent-specific error codes beyond the standard authentication and rate-limiting errors:
CodeHTTPDescription
AGENT_NOT_FOUND404Agent doesn’t exist or doesn’t belong to the authenticated account.
AGENT_NOT_TRAINED409Auto-resync needs at least one live source. Add a source and wait for it to reach trained.
AGENT_LIMIT_REACHED403The account has reached its plan’s maximum number of agents. Delete an existing agent or upgrade your plan.
PLAN_FEATURE_NOT_AVAILABLE403The requested feature is not available on the current plan. Upgrade to unlock it.