Skip to main content
DELETE
Delete Agent
Destructive
Recommended. This endpoint is part of the public /v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.
Soft-deletes an agent and all of its versions. The agent disappears from List Agents and can no longer be assigned to phone numbers or used for new calls, but historical call logs that reference it remain intact for auditing.

When to use this

  • Cleanup: remove test or superseded agents so pickers and audits only show agents that are in use.
  • Decommissioning: retire an agent after migrating its phone numbers and workflows to a replacement.

Before you call it

  • Reassign any phone numbers or active workflows that route to this agent first. Deleting an agent that live traffic depends on will break those calls.
  • Confirm the id with Get Agent Details; the delete is scoped to the workspace associated with your API key.

Result

This is a soft delete: the agent and all its versions are marked deleted rather than erased, so existing call history stays readable. A 404 Not Found means the agent does not exist in this workspace. See Errors for the standard error format.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

Agent ID

Example:

"agent_2g7Xy3tY53gRlp"

Response

Agent deleted successfully.

success
boolean
Example:

true

message
string
Example:

"Agent deleted successfully"