Skip to content

Delete a voice agent or twin

DELETE
/voice/agents/{agent_id}

Cascade-delete an agent or twin: its persona, identity, knowledge and parent settings row all go with it (voice’s own cascade, not something this proxy orchestrates). Requires the voice:write scope explicitly - see require_voice_agent_delete above for why this is self-gated rather than driving a new voice:delete scope.

org_id is pinned server-side; voice filters by (org_id, agent_id) so a cross-org agent_id 404s the same as GET/PUT.

Authorizations

Parameters

Path Parameters

agent_id
required

Agent UUID.

string

Agent UUID.

Header Parameters

X-Target-Org-Id
Any of:
string

Responses

200

Successful Response

object
data
required

Envelope for single-agent operations (create / get / update).

object
agent
Any of:

Complete agent configuration, as returned by create/get/update.

object
agent_id
required
string
agent_status
required
string
created_at
Any of:
created_by_email
Any of:
string
entity_type
required
string
id
required
integer
identity
required

Communication-channel identity for a voice agent (mirrors V2 IdentityV2).

object
avatar_url
Any of:
string
calendar
Any of:
integer
phone
Any of:
string
voice
Any of:
string
is_template
required
boolean
knowledge
required

Knowledge-collection attachments for a voice agent.

object
collections

Collection IDs (max 4).

Array<string>
org_id
required
string
persona
required

Persona / prompt configuration for a voice agent (mirrors V2 PersonaV2).

object
agent_name
required

Display name of the agent.

string
assertiveness_level
required

0.0=passive, 1.0=assertive.

number
<= 1
company_name_pronunciation
Any of:
string
conciseness_level
required

0.0=verbose, 1.0=brief.

number
<= 1
description
required

Brief summary of the agent’s purpose.

string
formality_level
required

0.0=casual, 1.0=formal.

number
<= 1
inbound_instructions
Any of:
string
outbound_instructions
Any of:
string
outbound_voicemail_prompt
Any of:
string
persona
required

Personality and behavior description.

string
role
required
string
template_id
Any of:
string
updated_at
Any of:
use_company_knowledge
required
boolean
message
Any of:
string
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string