Skip to main content
DELETE
/
api
/
v1
/
agents
/
{agent_id}
# Request 1: Delete a specific agent by ID
curl -X DELETE "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "message": "Agent deleted successfully"
}

​
Delete Agent

Permanently delete a voice agent and all its associated data including trainings, actions, and phone number associations. This action cannot be undone.

​
Endpoint

DELETE /api/v1/agents/{agent_id}

​
Path parameters

​
agent
string
required
The unique identifier of the voice agent to delete.

​
Request headers

​
Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here

​
Example requests

# Request 1: Delete a specific agent by ID
curl -X DELETE "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer talq_your_environment_token_here"

​
Response

​
Success Response (200 OK)

{
  "success": true,
  "message": "Agent deleted successfully"
}

​
Response fields

​
success
boolean
required
Indicates if the operation was successful.
​
message
string
required
Success message confirming the agent was deleted.

​
Error responses

​
404 Not Found

{
  "success": false,
  "message": "Agent not found"
}

​
401 Unauthorized

{
  "success": false,
  "message": "Unauthenticated."
}

​
403 Forbidden

{
  "success": false,
  "message": "You are not authorized to perform this action."
}

​
409 Conflict

{
  "success": false,
  "message": "Cannot delete agent while it has active calls."
}

​
Error codes

CodeDescriptionHTTP Status
AGENT_NOT_FOUNDSpecified agent does not exist404
INVALID_TOKENAuthentication token is invalid or missing401
UNAUTHORIZEDUser does not have permission to delete this agent403
AGENT_HAS_ACTIVE_CALLSAgent cannot be deleted while it has active calls409
AGENT_IS_PUBLISHEDPublished agents must be unpublished before deletion409

​
Important notes

This action is irreversible. Once an agent is deleted, all associated data including:
  • Agent configuration
  • Training data
  • Actions and webhooks
  • Phone number associations
  • Call history
Will be permanently removed and cannot be recovered.
Published agents must be unpublished first. If the agent is currently published, you must unpublish it before deletion.
  • List Agents: GET /api/v1/agents
  • Get Agent: GET /api/v1/agents/{agent_id}
  • Unpublish Agent: POST /api/v1/agents/{agent_id}/unpublish
  • Create Agent: POST /api/v1/agents