Delete Agent

Deletes an agent from Ultravox and removes the corresponding local agent_mappings record. Before deletion, it unassigns any phone numbers linked to the agent and checks for active call batches. Supports a keep_ultravox option to remove only the local mapping while preserving the agent in Ultravox.

Endpoint

Property	Value
Function Name	agents-delete
HTTP Method	DELETE
Authentication	Supabase JWT (Bearer token)
Required Role	agency_owner

Request

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Query Parameters

Field	Type	Required	Description
agent_id	string	Yes	The Ultravox agent ID to delete.
keep_ultravox	string	No	Set to "true" to only delete the local mapping and keep the agent in Ultravox. Defaults to false.

Response

Success (200)

{
  "success": true,
  "agent_id": "uv-agent-abc123",
  "agent_name": "My_Agent",
  "ultravox_deleted": true,
  "local_mapping_deleted": true,
  "was_managed_by_virsyn": true
}

Field	Description
agent_id	The Ultravox agent ID that was deleted.
agent_name	The agent's name from the local mapping, or null if no mapping existed.
ultravox_deleted	Whether the agent was deleted from Ultravox. false if keep_ultravox=true was set.
local_mapping_deleted	Whether the local mapping was deleted. false if no mapping existed or deletion failed.
was_managed_by_virsyn	Whether this agent was originally created through Virsyn.

Error Responses

Status	Condition
400	agent_id query parameter is missing
400	Agent has active call batches (status: pending, scheduled, or processing)
400	Ultravox API key is not configured for the agency
401	Missing or invalid authorization header
403	User is not associated with an agency
403	User role is not agency_owner
405	HTTP method is not DELETE
500	Failed to retrieve API credentials
500	Unexpected server error
502	Ultravox API returned an error during deletion (non-404)

Behavior

• Authenticates the user via Supabase JWT and verifies they belong to an agency with the agency_owner role. Unlike other agent management functions, only agency owners can delete agents.
• Validates the required agent_id query parameter and parses the optional keep_ultravox flag.
• Looks up the local agent_mappings record for the agent (scoped to the user's agency) to determine ownership and get the mapping ID.
• If a local mapping exists, checks for active phone numbers assigned to the agent mapping in agency_phone_numbers. If any are found, unassigns them by setting agent_mapping_id to null.
• Checks the call_batches table for any batches in pending, scheduled, or processing status linked to the agent mapping. If active batches exist, the deletion is blocked and a 400 error is returned with the count of active batches.
• Unless keep_ultravox=true is set:
  • Retrieves the agency's Ultravox API key.
  • Sends a DELETE request to https://api.ultravox.ai/api/agents/{agent_id}.
  • Treats a 404 response from Ultravox as successful (agent already gone).
• Deletes the local agent_mappings record (if one exists).
• Returns a summary of what was deleted.

Database Tables

Table	Operation	Description
users	Read	Fetches user profile to determine agency_id and role
agent_mappings	Read	Fetches the local mapping to check ownership and get the mapping ID
agency_phone_numbers	Read	Checks for active phone numbers assigned to the agent
agency_phone_numbers	Update	Unassigns phone numbers by setting agent_mapping_id to null
call_batches	Read	Checks for active batches linked to the agent mapping
agent_mappings	Delete	Removes the local mapping record

External APIs

API	Method	Endpoint	Description
Ultravox	DELETE	/api/agents/{agent_id}	Deletes the agent from Ultravox (unless keep_ultravox=true)

Related Functions

• Create Agent -- Create a new agent
• List Agents -- List all agents
• Get Agent -- Fetch a single agent with full details
• Update Agent -- Update an agent's configuration