Update a voice agent or twin

PUT

/voice/agents/{agent_id}

• Production
• QA

Partially update an agent. Only fields present in the body change.

persona / identity / knowledge are component-level replacements, not deep merges - matching voice’s own update semantics (send the field’s full sub-object to change any part of it). org_id is pinned server-side; a cross-org agent_id 404s the same as GET.

Authorizations

• BearerAuth

Parameters

Path Parameters

agent_id

required

Agent UUID.

string

Agent UUID.

Header Parameters

X-Target-Org-Id

Any of:

string

string

null

null

Request Body ^required

Body for partially updating a voice agent. Only supplied fields change.

object

agent_status

Any of:

string

string

Allowed values: active inactive archived

null

null

identity

Any of:

VoiceAgentIdentity

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

object

avatar_url

Any of:

string

string

null

null

calendar

Any of:

integer

integer

null

null

phone

Any of:

string

string

null

null

voice

Any of:

string

string

null

null

null

null

is_template

Any of:

boolean

boolean

null

null

knowledge

Any of:

VoiceAgentKnowledge

Knowledge-collection attachments for a voice agent.

object

collections

Collection IDs (max 4).

Array<string>

null

null

persona

Any of:

VoiceAgentPersona

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

string

null

null

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

string

null

null

outbound_instructions

Any of:

string

string

null

null

outbound_voicemail_prompt

Any of:

string

string

null

null

persona

required

Personality and behavior description.

string

null

null

role

Any of:

string

string

null

null

use_company_knowledge

Any of:

boolean

boolean

null

null

Responses

200

Successful Response

object

data

required

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

object

agent

Any of:

VoiceAgentDetail

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

object

agent_id

required

string

agent_status

required

string

created_at

Any of:

unknown

null

null

created_by_email

Any of:

string

string

null

null

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

string

null

null

calendar

Any of:

integer

integer

null

null

phone

Any of:

string

string

null

null

voice

Any of:

string

string

null

null

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

string

null

null

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

string

null

null

outbound_instructions

Any of:

string

string

null

null

outbound_voicemail_prompt

Any of:

string

string

null

null

persona

required

Personality and behavior description.

string

role

required

string

template_id

Any of:

string

string

null

null

updated_at

Any of:

unknown

null

null

use_company_knowledge

required

boolean

null

null

message

Any of:

string

string

null

null

pagination

Any of:

PaginationMeta

object

has_next

required

Whether there are more pages

boolean

limit

required

Items per page

integer

next_cursor

Any of:

string

string

null

null

page

required

Current page number (1-indexed)

integer

total

required

Total number of items

integer

null

null

422

Validation Error

object

detail

Array<object>

object

loc

required

Array

msg

required

string

type

required

string