Update Agent (Full)

Authorizations

X-CEKURA-API-KEY

string

header

required

API Key Authentication. It should be included in the header of each request.

Path Parameters

integer

required

A unique integer value identifying this ai agent.

Body

Update an AI voice agent.

agent_name

string

required

A descriptive name for your agent Example:

"Customer Service Assistant"
"Sales Bot"

Maximum string length: 255

inbound

boolean

required

Whether this agent handles inbound calls.

If true, our agent will call you on above number.
If false, your agent will have to call our agent.

Example: true or false

description

string

required

A detailed description of what this agent does and how it should interact Example:

AI agent for handling customer support inquiries and resolving technical issues

contact_number

string

Phone number assigned to this agent for calls (must start with + followed by digits, min 8 chars) Example: "+1234567890"

Maximum string length: 30

language

enum<string>

default:en

The primary language this agent uses for communication (e.g. 'en' for English)

af - Afrikaans
ar - Arabic
bn - Bengali
bg - Bulgarian
zh - Chinese Simplified
cs - Czech
da - Danish
nl - Dutch
en - English
et - Estonian
fi - Finnish
fr - French
de - German
el - Greek
gu - Gujarati
hi - Hindi
he - Hebrew
hu - Hungarian
id - Indonesian
it - Italian
ja - Japanese
kn - Kannada
ko - Korean
ms - Malay
ml - Malayalam
mr - Marathi
multi - Multilingual
no - Norwegian
pl - Polish
pa - Punjabi
pt - Portuguese
ro - Romanian
ru - Russian
sk - Slovak
es - Spanish
sv - Swedish
th - Thai
tr - Turkish
tl - Tagalog
ta - Tamil
te - Telugu
uk - Ukrainian
vi - Vietnamese

Available options:

af,

ar,

bn,

bg,

zh,

cs,

da,

nl,

en,

et,

fi,

fr,

de,

el,

gu,

hi,

he,

hu,

id,

it,

ja,

kn,

ko,

ms,

ml,

mr,

multi,

no,

pl,

pa,

pt,

ro,

ru,

sk,

es,

sv,

th,

tr,

tl,

ta,

te,

uk,

vi

assistant_id

string | null

External assistant service identifier (minimum 10 characters). Example: "asst_abc123xyz".

Note: assistant_id alone does NOT substitute for provider credentials. Providers like VAPI, Retell, and Bland still require their respective *_api_key to be set.

Maximum string length: 255

chat_assistant_id

string

Chat / provider-specific assistant identifier (minimum 10 characters). Example: "chat_asst_abc123xyz".

Required for assistant_provider values:

retell — the Retell agent id (used for voice too, despite the field name).
bland — the Bland pathway_id (Bland calls it pathway_id internally).
sms / whatsapp — the text-channel assistant id.

Maximum string length: 255

websocket_url

string | null

WebSocket endpoint URL for real-time communication Example: "wss://api.example.com/ws"

websocket_headers

object

Headers to be sent to the websocket server

Show child attributes

llm_system_prompt

string

System prompt that defines the agent's behavior and personality Example:

You are a helpful customer service agent. Always be polite and professional.

llm_model

enum<string>

default:gpt-4o

The LLM model to use for simulating user responses

gpt-4o - gpt-4o
gpt-4o-mini - gpt-4o-mini
gpt-4.1 - gpt-4.1
gpt-4.1-mini - gpt-4.1-mini
claude-sonnet-4-5-20250929 - claude-sonnet-4-5

Available options:

gpt-4o,

gpt-4o-mini,

gpt-4.1,

gpt-4.1-mini,

claude-sonnet-4-5-20250929

llm_temperature

number<double>

default:0

Controls randomness in responses (0.0-2.0, lower = more focused) Example: 0.5

llm_max_tokens

integer

default:4096

Maximum length of simulated responses in tokens Example: 4096

outbound_auto_call

boolean

default:false

Whether to automatically call the outbound number Example: False or True

sip_endpoint

string | null

SIP endpoint URL for direct SIP-based phone calls. Example: "sip:agent@cekura.ai" or "sip:contact@domain.com" Leave empty if SIP calling is not configured for this agent.

Maximum string length: 255

sip_auth

any | null

SIP authentication credentials Example: {"username": "user123", "password": "pass123"}

predefined_metrics

any

write-only

predefined metrics to use for the agent

transcript_provider

enum<string>

default:""

Service provider for speech-to-text transcription

vapi - Vapi
retell - Retell
synthflow - Synthflow
elevenlabs - Elevenlabs
bland - Bland
livekit - Livekit
pipecat - Pipecat
koreai - Kore
custom - Custom
trillet - Trillet
cisco - Cisco
genesys - Genesys
chirp - Chirp

Available options:

vapi,

retell,

synthflow,

elevenlabs,

bland,

livekit,

pipecat,

koreai,

custom,

trillet,

cisco,

genesys,

chirp,

assistant_provider

enum<string>

default:""

Service provider for the AI assistant functionality. Valid values (live enum):

self_hosted — websocket or observation-only; no api_key needed. Use websocket_url + websocket_headers for text-mode runs.
vapi — requires vapi_api_key; optional assistant_id, vapi_data.public_key.
retell — requires retell_api_key AND chat_assistant_id (used for voice too).
bland — requires bland_api_key AND chat_assistant_id (Bland calls this pathway_id); bland_data.encrypted_key for Twilio.
livekit — requires livekit_api_key + livekit_data.api_secret + livekit_data.url.
elevenlabs — requires elevenlabs_api_key.
agentforce — requires agentforce_client_secret + agentforce_data.
trillet — requires trillet_api_key + trillet_data.workspace_id.
cisco — Cisco Webex.
vocera — Cekura-hosted.
sms / whatsapp — text-only channels; use chat_assistant_id.
"" (empty) — unset; agent is not runnable until a provider is configured.

Note: the serializer also exposes pipecat_*, synthflow_*, koreai_*, genesys_*, custom_provider_* fields, but those provider values are not currently selectable in this enum.

vapi - Vapi
retell - Retell
elevenlabs - Elevenlabs
vocera - Vocera
sms - Sms
whatsapp - Whatsapp
self_hosted - Self Hosted
agentforce - Agentforce
trillet - Trillet
cisco - Cisco
bland - Bland
livekit - Livekit

Available options:

vapi,

retell,

elevenlabs,

vocera,

sms,

whatsapp,

self_hosted,

agentforce,

trillet,

cisco,

bland,

livekit,

vapi_api_key

string

write-only

API key for VAPI service provider. Required when assistant_provider="vapi". Example: "vapi_api_key_123"

retell_api_key

string

write-only

API key for Retell service provider. Required when assistant_provider="retell" (along with chat_assistant_id). Example: "retell_api_key_123"

elevenlabs_api_key

string

write-only

API key for ElevenLabs voice synthesis service. Required when assistant_provider="elevenlabs". Example: "elevenlabs_api_key_123"

bland_api_key

string

write-only

API key for Bland service provider. Required when assistant_provider="bland" (along with chat_assistant_id, which Bland calls pathway_id). Example: "bland_api_key_123"

bland_data

string

Bland additional configuration. Pass encrypted_key containing the Twilio credential bundle. Example: {"encrypted_key": "twillio_encrypted_key"}

livekit_api_key

string

write-only

API key for LiveKit service provider. Required when assistant_provider="livekit" (also requires livekit_data.api_secret and livekit_data.url). Example: "livekit_api_key_123"

livekit_data

string

LiveKit additional data (api_secret, url, and config). Required alongside livekit_api_key when assistant_provider="livekit". On response, secrets are masked (the api_secret key is stripped and replaced with api_secret_configured: true).

pipecat_api_key

string

write-only

API key for Pipecat/Daily.co service provider Example: "pipecat_api_key_123"

pipecat_data

string

Pipecat/Daily.co additional data (webhook_url and config)

koreai_client_secret

string

write-only

Client secret key for Kore.ai service provider Example: "client_secret_key_123"

koreai_data

string

Kore.ai additional data - client_id, bot_id, and host (optional)

genesys_client_secret

string

write-only

Client secret key for Genesys Cloud service provider

genesys_data

string

Genesys Cloud additional data - client_id and region

agentforce_client_secret

string

write-only

Client secret for Salesforce Agentforce OAuth2 authentication Example: "3EG7HHH..."

agentforce_data

string

Agentforce additional data - client_id, domain, and agent_id Example: {"client_id": "sd7a8...", "domain": "https://example.sandbox.my.salesforce.com", "agent_id": "0Xx..."}

custom_provider_api_key

string

write-only

API key for custom service provider Example: "custom_api_key_123"

custom_provider_data

string

Additional configuration data for custom service provider

vapi_data

string

VAPI additional configuration data Example: {"public_key": "your-vapi-public-key", "trigger_url": "https://example.com/trigger"}

retell_data

string

Retell additional configuration data Example: {"trigger_url": "https://example.com/trigger"}

elevenlabs_data

string

ElevenLabs additional configuration data Example: {"trigger_url": "https://example.com/trigger"}

trillet_api_key

string

write-only

API key for Trillet AI service provider Example: "trillet_api_key_123"

trillet_data

string

Trillet AI additional data including Workspace ID Example: {"workspace_id": "1234567890"}

chirp_data

string

Configuration for CHIRP WebSocket voice integration. Supported keys: chirp_websocket_url (required): the wss:// endpoint to dial. chirp_basic_auth_username (optional): username for Basic Auth on WS upgrade. chirp_basic_auth_password (optional): password for Basic Auth on WS upgrade. Example: {"chirp_websocket_url": "wss://your-host/voice", "chirp_basic_auth_username": "user", "chirp_basic_auth_password": "secret"}

synthflow_api_key

string

write-only

API key for Synthflow service provider Example: "synthflow_api_key_123"

synthflow_data

string

Synthflow additional configuration data Example: {"synthflow_base_url_override": "https://api.synthflow.ai"}

dropoff_nodes

any

Configuration for conversation dropoff points. Example: {"timeout": 30, "max_retries": 3}

topic_nodes

any

Configuration for topic classification nodes. Example: {"billing": "handle_billing", "support": "handle_support"}

pronunciation_words

any | null

List of words with phonemes for pronunciation analysis. Example: [["hello", "HH AH L OW"], ["world", "W ER L D"]]

spelling_word_types

any | null

List of word types/categories to check for spelling analysis. Example: ["name", "postcode", "email", "address"]

auto_update_dropoff_nodes

boolean

Whether to automatically update the dropoff nodes based on the agent description

auto_update_topic_nodes

boolean

Whether to automatically update the topic nodes based on the agent description

hallucination_metric_kb_files

(integer | null)[]

Knowledge base files used for hallucination metric

outbound_numbers

any

List of phone numbers authorized to place outbound calls for this agent. Example: ["+1234567890", "+0987654321"]

Used for webhook validation — when an inbound webhook arrives, the system checks whether the calling number is in this list (falls back to contact_number if the list is empty). Actual call placement for test runs uses the scenario's configured phone number or a number allocated from the organisation's phone pool.

auto_fetch_calls_enabled

boolean

default:false

Enable automatic fetching of calls every 30 seconds (VAPI/Retell only)

auto_sync_prompt_enabled

boolean

Enable automatic syncing of prompts from Retell/VAPI/ElevenLabs API every 30 seconds

agent_gives_first_message

boolean | null

Whether the main agent (not the testing agent) will give the first message. True = agent speaks first (testing agent won't generate a first message). False = testing agent speaks first (first message will be generated). None = preference not yet set.

Response

agent_name

string

required

A descriptive name for your agent Example:

"Customer Service Assistant"
"Sales Bot"

Maximum string length: 255

inbound

boolean

required

Whether this agent handles inbound calls.

If true, our agent will call you on above number.
If false, your agent will have to call our agent.

Example: true or false

description

string

required

A detailed description of what this agent does and how it should interact Example:

AI agent for handling customer support inquiries and resolving technical issues

integer

read-only

Agent ID. Example: 2142

project

integer

The project this agent belongs to

contact_number

string

Phone number assigned to this agent for calls (must start with + followed by digits, min 8 chars) Example: "+1234567890"

Maximum string length: 30

language

enum<string>

default:en

The primary language this agent uses for communication (e.g. 'en' for English)

af - Afrikaans
ar - Arabic
bn - Bengali
bg - Bulgarian
zh - Chinese Simplified
cs - Czech
da - Danish
nl - Dutch
en - English
et - Estonian
fi - Finnish
fr - French
de - German
el - Greek
gu - Gujarati
hi - Hindi
he - Hebrew
hu - Hungarian
id - Indonesian
it - Italian
ja - Japanese
kn - Kannada
ko - Korean
ms - Malay
ml - Malayalam
mr - Marathi
multi - Multilingual
no - Norwegian
pl - Polish
pa - Punjabi
pt - Portuguese
ro - Romanian
ru - Russian
sk - Slovak
es - Spanish
sv - Swedish
th - Thai
tr - Turkish
tl - Tagalog
ta - Tamil
te - Telugu
uk - Ukrainian
vi - Vietnamese

Available options:

af,

ar,

bn,

bg,

zh,

cs,

da,

nl,

en,

et,

fi,

fr,

de,

el,

gu,

hi,

he,

hu,

id,

it,

ja,

kn,

ko,

ms,

ml,

mr,

multi,

no,

pl,

pa,

pt,

ro,

ru,

sk,

es,

sv,

th,

tr,

tl,

ta,

te,

uk,

vi

assistant_id

string | null

External assistant service identifier (minimum 10 characters). Example: "asst_abc123xyz".

Note: assistant_id alone does NOT substitute for provider credentials. Providers like VAPI, Retell, and Bland still require their respective *_api_key to be set.

Maximum string length: 255

chat_assistant_id

string

Chat / provider-specific assistant identifier (minimum 10 characters). Example: "chat_asst_abc123xyz".

Required for assistant_provider values:

retell — the Retell agent id (used for voice too, despite the field name).
bland — the Bland pathway_id (Bland calls it pathway_id internally).
sms / whatsapp — the text-channel assistant id.

Maximum string length: 255

websocket_url

string | null

WebSocket endpoint URL for real-time communication Example: "wss://api.example.com/ws"

websocket_headers

object

Headers to be sent to the websocket server

Show child attributes

llm_system_prompt

string

System prompt that defines the agent's behavior and personality Example:

You are a helpful customer service agent. Always be polite and professional.

llm_model

enum<string>

default:gpt-4o

The LLM model to use for simulating user responses

gpt-4o - gpt-4o
gpt-4o-mini - gpt-4o-mini
gpt-4.1 - gpt-4.1
gpt-4.1-mini - gpt-4.1-mini
claude-sonnet-4-5-20250929 - claude-sonnet-4-5

Available options:

gpt-4o,

gpt-4o-mini,

gpt-4.1,

gpt-4.1-mini,

claude-sonnet-4-5-20250929

llm_temperature

number<double>

default:0

Controls randomness in responses (0.0-2.0, lower = more focused) Example: 0.5

llm_max_tokens

integer

default:4096

Maximum length of simulated responses in tokens Example: 4096

outbound_auto_call

boolean

default:false

Whether to automatically call the outbound number Example: False or True

sip_endpoint

string | null

SIP endpoint URL for direct SIP-based phone calls. Example: "sip:agent@cekura.ai" or "sip:contact@domain.com" Leave empty if SIP calling is not configured for this agent.

Maximum string length: 255

sip_auth

any | null

SIP authentication credentials Example: {"username": "user123", "password": "pass123"}

knowledge_base_files

string

read-only

List of knowledge base files attached to the agent Example: [1, 2, 3]

transcript_provider

enum<string>

default:""

Service provider for speech-to-text transcription

vapi - Vapi
retell - Retell
synthflow - Synthflow
elevenlabs - Elevenlabs
bland - Bland
livekit - Livekit
pipecat - Pipecat
koreai - Kore
custom - Custom
trillet - Trillet
cisco - Cisco
genesys - Genesys
chirp - Chirp

Available options:

vapi,

retell,

synthflow,

elevenlabs,

bland,

livekit,

pipecat,

koreai,

custom,

trillet,

cisco,

genesys,

chirp,

assistant_provider

enum<string>

default:""

Service provider for the AI assistant functionality. Valid values (live enum):

self_hosted — websocket or observation-only; no api_key needed. Use websocket_url + websocket_headers for text-mode runs.
vapi — requires vapi_api_key; optional assistant_id, vapi_data.public_key.
retell — requires retell_api_key AND chat_assistant_id (used for voice too).
bland — requires bland_api_key AND chat_assistant_id (Bland calls this pathway_id); bland_data.encrypted_key for Twilio.
livekit — requires livekit_api_key + livekit_data.api_secret + livekit_data.url.
elevenlabs — requires elevenlabs_api_key.
agentforce — requires agentforce_client_secret + agentforce_data.
trillet — requires trillet_api_key + trillet_data.workspace_id.
cisco — Cisco Webex.
vocera — Cekura-hosted.
sms / whatsapp — text-only channels; use chat_assistant_id.
"" (empty) — unset; agent is not runnable until a provider is configured.

Note: the serializer also exposes pipecat_*, synthflow_*, koreai_*, genesys_*, custom_provider_* fields, but those provider values are not currently selectable in this enum.

vapi - Vapi
retell - Retell
elevenlabs - Elevenlabs
vocera - Vocera
sms - Sms
whatsapp - Whatsapp
self_hosted - Self Hosted
agentforce - Agentforce
trillet - Trillet
cisco - Cisco
bland - Bland
livekit - Livekit

Available options:

vapi,

retell,

elevenlabs,

vocera,

sms,

whatsapp,

self_hosted,

agentforce,

trillet,

cisco,

bland,

livekit,

vapi_api_key_configured

string

read-only

vapi_public_key_configured

string

read-only

retell_api_key_configured

string

read-only

elevenlabs_api_key_configured

string

read-only

bland_api_key_configured

string

read-only

bland_data

string

Bland additional configuration. Pass encrypted_key containing the Twilio credential bundle. Example: {"encrypted_key": "twillio_encrypted_key"}

livekit_api_key_configured

string

read-only

livekit_data

string

pipecat_api_key_configured

string

read-only

pipecat_data

string

Pipecat/Daily.co additional data (webhook_url and config)

koreai_client_secret_configured

string

read-only

koreai_data

string

Kore.ai additional data - client_id, bot_id, and host (optional)

genesys_client_secret_configured

string

read-only

genesys_data

string

Genesys Cloud additional data - client_id and region

agentforce_client_secret_configured

string

read-only

agentforce_data

string

Agentforce additional data - client_id, domain, and agent_id Example: {"client_id": "sd7a8...", "domain": "https://example.sandbox.my.salesforce.com", "agent_id": "0Xx..."}

custom_provider_api_key_configured

string

read-only

custom_provider_data

string

Additional configuration data for custom service provider

vapi_data

string

VAPI additional configuration data Example: {"public_key": "your-vapi-public-key", "trigger_url": "https://example.com/trigger"}

retell_data

string

Retell additional configuration data Example: {"trigger_url": "https://example.com/trigger"}

elevenlabs_data

string

ElevenLabs additional configuration data Example: {"trigger_url": "https://example.com/trigger"}

trillet_api_key_configured

string

read-only

trillet_data

string

Trillet AI additional data including Workspace ID Example: {"workspace_id": "1234567890"}

chirp_data

string

synthflow_api_key_configured

string

read-only

synthflow_data

string

Synthflow additional configuration data Example: {"synthflow_base_url_override": "https://api.synthflow.ai"}

enabled_personalities

integer[]

read-only

Personality profiles enabled for this agent Example: [1, 2, 3]

dropoff_nodes

any

Configuration for conversation dropoff points. Example: {"timeout": 30, "max_retries": 3}

topic_nodes

any

Configuration for topic classification nodes. Example: {"billing": "handle_billing", "support": "handle_support"}

pronunciation_words

any | null

List of words with phonemes for pronunciation analysis. Example: [["hello", "HH AH L OW"], ["world", "W ER L D"]]

spelling_word_types

any | null

List of word types/categories to check for spelling analysis. Example: ["name", "postcode", "email", "address"]

auto_update_dropoff_nodes

boolean

Whether to automatically update the dropoff nodes based on the agent description

auto_update_topic_nodes

boolean

Whether to automatically update the topic nodes based on the agent description

hallucination_metric_kb_files

(integer | null)[]

Knowledge base files used for hallucination metric

outbound_numbers

any

List of phone numbers authorized to place outbound calls for this agent. Example: ["+1234567890", "+0987654321"]

created_at

string<date-time>

read-only

Timestamp when the agent was created Example: "2021-01-01T00:00:00Z"

updated_at

string<date-time>

read-only

Timestamp when the agent was last updated Example: "2021-01-01T00:00:00Z"

auto_fetch_calls_enabled

boolean

default:false

Enable automatic fetching of calls every 30 seconds (VAPI/Retell only)

auto_sync_prompt_enabled

boolean

Enable automatic syncing of prompts from Retell/VAPI/ElevenLabs API every 30 seconds

agent_gives_first_message

boolean | null

API Reference

Documentation Index

Authorizations

Path Parameters

Body

Response