Create Agent

Register an AI voice agent with Cekura. Provider credentials are nested under a provider block rather than flat fields.

POST /test_framework/v2/aiagents/

Create an AI voice agent

cURL

curl --request POST \
  --url https://api.cekura.ai/test_framework/v2/aiagents/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "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": {
      "api_key": "<string>",
      "config": {
        "public_key": "<string>",
        "trigger_url": "<string>",
        "trigger_secret": "<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,
    "redact_fields": [],
    "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
      }
    }
  ],
  "mock_tools_enabled": true,
  "dynamic_variables": [
    {
      "name": "<string>",
      "description": "<string>",
      "id": 123
    }
  ],
  "email_id": "[e-mail]"
}
'

201

{
  "id": 303,
  "name": "Support Bot",
  "description": "Handles inbound support calls",
  "project": 42,
  "language": "en",
  "telephony": {
    "inbound": true,
    "phone_number": "[phone]",
    "sip_uri": null
  },
  "provider": {
    "type": "custom"
  },
  "agent_speaks_first": null,
  "knowledge_base_files": [],
  "mock_tools": [
    {
      "id": 1,
      "name": "get_order",
      "description": "Look up an order",
      "mock_data": [
        {
          "input": {
            "order_id": "A1"
          },
          "output": {
            "status": "shipped"
          }
        }
      ],
      "served_via": {
        "type": "direct",
        "url": "https://api.cekura.ai/test_framework/v1/aiagents/303/tool/get_order/"
      }
    },
    {
      "id": 2,
      "name": "crm_lookup",
      "description": "CRM read",
      "mock_data": [],
      "served_via": {
        "type": "mcp",
        "mock_index": 1,
        "url": "https://api.cekura.ai/test_framework/v1/aiagents/303/mcp/1/"
      }
    }
  ],
  "mock_tools_enabled": false,
  "mock_tools_provider": null,
  "dynamic_variables": [
    {
      "id": 10,
      "name": "customer_name",
      "description": "Caller name"
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Authorizations

oauth2supabase_sessionapi_key

Authorization · string · header · required

OAuth access token issued by Cekura for connected apps.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

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

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.

Show child attributes

provider · object

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

Show child attributes

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.

Show child attributes

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 · write-only

Secret sent in X-CEKURA-SECRET header. Applies when agent webhook_url is set. Write-only — never returned in API responses. Use webhook_secret_configured to check whether one 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.

Show child attributes

mock_tools_enabled · boolean

Whether mock tools should be selected by default when configuring a run.

dynamic_variables · object[] · write-only

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

Show child attributes

email_id · string<email> | null

Email address this agent receives at. When set, enables email-based test runs.

Maximum string length: 254

Response

201

application/json

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.

Show child attributes

provider · object

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

Show child attributes

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.

Show child attributes

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_configured · string · read-only

mock_tools · object[] · read-only

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

Show child attributes

mock_tools_enabled · boolean

Whether mock tools should be selected by default when configuring a run.

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.

Show child attributes

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"

email_id · string<email> | null

Email address this agent receives at. When set, enables email-based test runs.

Maximum string length: 254