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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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. You can find this in your dashboard under Voice Agents.

​
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.

​
Best Practices

  1. Verify agent status - Check if the agent is published before attempting deletion
  2. Backup important data - Export any training data or configurations you want to keep
  3. Check for active calls - Ensure no calls are currently in progress
  4. Update integrations - Remove any webhook URLs or integrations that reference this agent
  5. Notify team members - Inform other users who might be using this agent
  • 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