Delete an agent

Deletes an agent. The steps run in this order:

1. Every active campaign that uses the agent is set to paused.
2. The agent’s phone numbers are unbound at the voice provider (best effort).
3. The voice agent is deleted in the voice engine. If that fails the request fails and nothing else is deleted — but the campaigns paused in step 1 stay paused.
4. In one transaction the agent is soft-deleted together with its tools, A/B variants, widgets, knowledge documents and MCP server assignments, and its phone numbers are detached.
5. The agent’s MCP gateway identity is retired and a final delete version is recorded.

The agent’s history (calls, conversations, change versions) is kept.

Side effects. Pauses campaigns, calls the voice engine (unbind numbers, delete agent), disables the agent’s widgets, posts an in-app notification and writes an audit entry. Inbound calls to numbers that pointed at the agent stop being answered until another agent is assigned.

Idempotency. Safe to retry: a second call answers 404 AGENT_NOT_FOUND. Retrying after a 502 re-attempts the provider deletion.

Webhook events. campaign.paused ({ campaign_id, campaign_name, agent_id, channel, status: paused, reason: agent_deleted }) for each active campaign the deletion pauses, and audit.log_recorded (when subscribed). See Webhooks.

Access

• Required scope: full. Admin-only: API keys with write are refused; signed-in users need the owner or admin role.
• Rate limit: Agent mutations — 10 requests/min per workspace, shared with every agent, A/B variant, tool and knowledge write; the request also counts against the General API limit. See Rate limits.
• Plan: Available on every plan.