Skip to main content
PATCH
/
test_framework
/
v2
/
aiagents
/
{id}
Update an AI voice agent (partial)
curl --request PATCH \
  --url https://api.cekura.ai/test_framework/v2/aiagents/{id}/ \
  --header 'Content-Type: application/json' \
  --header 'X-CEKURA-API-KEY: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "project": 123,
  "language": "en",
  "telephony": {
    "phone_number": "<string>",
    "inbound": false,
    "sip_uri": "<string>",
    "sip_auth": "<unknown>",
    "websocket_url": "<string>",
    "websocket_auth": "<unknown>",
    "outbound_numbers": [
      "<string>"
    ]
  },
  "provider": {
    "agent_id": "<string>",
    "credentials": {
      "api_key": "<string>",
      "config": {
        "public_key": "<string>",
        "trigger_url": "<string>"
      }
    },
    "chat_agent_details": {
      "config": {
        "agent_id": "<string>"
      }
    },
    "auto_dial_outbound": true,
    "auto_import_calls": true,
    "auto_sync_prompt": true,
    "send_post_conversation_metadata": true,
    "configure_from_provider": false
  },
  "agent_speaks_first": true,
  "predefined_metrics": "<unknown>",
  "knowledge_base_files": [
    {
      "id": 123,
      "file_name": "<string>",
      "name": "<string>",
      "content_base64": "<string>"
    }
  ],
  "webhook_url": "<string>",
  "webhook_secret": "<string>",
  "mock_tools": [
    {
      "id": 123,
      "name": "<string>",
      "description": "<string>",
      "mock_data": "<unknown>",
      "freetext_params": [
        "<string>"
      ],
      "served_via": {
        "type": "direct",
        "mock_index": 2
      }
    }
  ],
  "dynamic_variables": [
    {
      "name": "<string>",
      "description": "<string>",
      "id": 123
    }
  ]
}
'
{
  "description": "<string>",
  "id": 123,
  "name": "<string>",
  "project": 123,
  "language": "en",
  "telephony": {
    "phone_number": "<string>",
    "inbound": false,
    "sip_uri": "<string>",
    "sip_auth": "<unknown>",
    "websocket_url": "<string>",
    "websocket_auth": "<unknown>",
    "outbound_numbers": [
      "<string>"
    ]
  },
  "provider": {
    "agent_id": "<string>",
    "credentials": {
      "config": {
        "public_key": "<string>",
        "trigger_url": "<string>"
      }
    },
    "chat_agent_details": {
      "config": {
        "agent_id": "<string>"
      }
    },
    "auto_dial_outbound": true,
    "auto_import_calls": true,
    "auto_sync_prompt": true,
    "send_post_conversation_metadata": true
  },
  "agent_speaks_first": true,
  "knowledge_base_files": [
    {
      "agent": 123,
      "id": 123,
      "file_url": "<string>",
      "file_name": "<string>",
      "file_type": "<string>",
      "file_size": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "enabled_personalities": [
    123
  ],
  "webhook_url": "<string>",
  "webhook_secret": "<string>",
  "mock_tools": [
    {
      "id": 123,
      "name": "<string>",
      "description": "<string>",
      "mock_data": "<unknown>",
      "served_via": {
        "url": "<string>",
        "mock_index": 123
      }
    }
  ],
  "mock_tools_enabled": true,
  "mock_tools_provider": "<string>",
  "dynamic_variables": [
    {
      "id": 123,
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
X-CEKURA-API-KEY
string
header
required

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

Path Parameters

​
id
integer
required

A unique integer value identifying this ai agent.

Body

​
name
string

Agent name. Optional when configure_from_provider is set — it's fetched from the provider.

Maximum string length: 255
​
description
string

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
​
project
integer

The project this agent belongs to

​
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
​
telephony
object

Phone and SIP/websocket channel configuration.

​
provider
object

AI platform integration. Nested credentials replace the flat {provider}_api_key fields.

​
agent_speaks_first
boolean | null

True = agent speaks first; False = test user speaks first; null = auto-detect.

​
predefined_metrics
any
write-only

predefined metrics to use for the agent

​
knowledge_base_files
object[]
write-only

Full desired set of knowledge base files. Reference existing by id; add new ones with file_name + content_base64. Omitted existing files are deleted.

​
webhook_url
string<uri>

Webhook URL for this agent. When set, overrides the project-level webhook URL for events from this agent.

​
webhook_secret
string

Secret sent in X-CEKURA-SECRET header. Applies when agent webhook_url is set.

​
mock_tools
object[]
write-only

Full desired set of mock tools. Items with id (or a matching name) update existing tools; items without create new ones. Omitted existing tools are deleted.

​
dynamic_variables
object[]
write-only

Full desired set of dynamic variable definitions, matched by name. Omitted existing variables are deleted.

Response

​
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
​
id
integer
read-only

Agent ID. Example: 2142

​
name
string

Agent name. Optional when configure_from_provider is set — it's fetched from the provider.

Maximum string length: 255
​
project
integer

The project this agent belongs to

​
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
​
telephony
object

Phone and SIP/websocket channel configuration.

​
provider
object

AI platform integration (provider type, agent id, credential status, chat config).

​
agent_speaks_first
boolean | null

True = agent speaks first; False = test user speaks first; null = auto-detect.

​
knowledge_base_files
object[]
read-only

Knowledge base files attached to the agent.

​
enabled_personalities
integer[]
read-only

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

​
webhook_url
string<uri>

Webhook URL for this agent. When set, overrides the project-level webhook URL for events from this agent.

​
webhook_secret
string

Secret sent in X-CEKURA-SECRET header. Applies when agent webhook_url is set.

​
mock_tools
object[]
read-only

Mock tools registered on the agent, each with its mock data and runtime access (served_via).

​
mock_tools_enabled
boolean
read-only

Whether mock-tool mode is currently active on the provider. Default false.

​
mock_tools_provider
string | null
read-only

Provider the mock tools were fetched from (vapi, retell, elevenlabs, custom). Null until auto-fetch has been run.

​
dynamic_variables
object[]
read-only

Dynamic variable definitions for the agent, ordered by name.

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