--- title: "Create an AI voice agent" method: POST path: "/test_framework/v2/aiagents/" tags: ["test_framework"] --- # Create an AI voice agent `POST /test_framework/v2/aiagents/` ## Request - Base URL: `https://api.cekura.ai` - URL: `https://api.cekura.ai/test_framework/v2/aiagents/` - Auth: one of: - API key in header `X-CEKURA-API-KEY` - HTTP bearer - HTTP bearer Register a new AI voice agent. Required fields: name, description, project, inbound. Provider credentials are nested under provider.{type, agent_id, credentials} instead of flat fields. transcript_provider defaults to provider.type when omitted. **provider.credentials keys by type (voice providers only):** - vapi: api_key + config.{public_key, trigger_url} - retell: api_key + agent_id + optional chat_agent_details.config.agent_id - elevenlabs: api_key + config.{trigger_url} - bland: api_key + agent_id (pathway_id) + config.{encrypted_key} for Twilio - livekit: api_key + config.{api_secret (required), url (required)} - pipecat: api_key + config.{webhook_url} - cisco: no credentials needed to dial; connect Webex Contact Center from the dashboard for transcripts - gemini_cx: no api_key; agent_id (CX agent id) + config.{service_account_email, location}; config.project_id defaults from the email - self-hosted chat: provider.type=custom + chat_agent_details.{type: self_hosted, config.{url (wss://), headers}} Note: agentforce goes in chat_agent_details; koreai/genesys/synthflow use the v1 API. **Auto-import from a cloud provider** — set `provider.configure_from_provider: true` (vapi/retell/elevenlabs/synthflow/bland) with `provider.agent_id` + `provider.credentials.api_key`, or agentforce with `chat_agent_details.config.{agent_id, client_id, client_secret, domain}` (omit the key to use the project's saved provider key; list importable ids with `GET /v2/aiagents/provider-assistants/`). An assistant already imported into the project is refused with **409**. Cekura fetches the prompt, name, language, who-speaks-first, phone number, tool calls, dynamic variables and knowledge base and configures the agent automatically — `name` and `description` become optional (auto-fetched). The response is **202** with the created agent plus a `progress_id`; poll `auto-fetch-progress/` to follow the staged import. See examples below for full per-provider payloads. ## Request body - SchemaPostAIAgentV2 - `id` integer: Agent ID. Example: `2142` - `name` string: Agent name. Optional when configure_from_provider is set — it's fetched from the provider. - `description` string, required: A detailed description of what this agent does and how it should interact Example: ```text AI agent for handling customer support inquiries and resolving technical issues ``` - `project` integer: The project this agent belongs to - `language` 'af' | 'ar' | 'bn' | 'bg' | 'zh' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'gu' | 'hi' | 'he' | 'hu' | 'id' | 'it' | 'ja' | 'kn' | 'kk' | 'ko' | 'ms' | 'ml' | 'mr' | 'multi' | 'no' | 'pl' | 'pa' | 'pt' | 'ro' | 'ru' | 'sk' | 'es' | 'sv' | 'th' | 'tr' | 'tl' | 'ta' | 'te' | 'uk' | 'uz' | 'vi': 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 * `kk` - Kazakh * `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 * `uz` - Uzbek * `vi` - Vietnamese - `telephony` AgentTelephony: Phone / SIP / websocket voice channel configuration for the agent. - `phone_number` string: The agent's own E.164 number, not a customer's: Cekura dials it for inbound tests, and the agent's outbound calls come from it. E.g. +14155551234. - `inbound` boolean: True = agent receives inbound calls; False = outbound only. A property of the agent, not of one run: never flip it to change who dials whom. To dial a different number in a run, pass `outbound_phone_number` to the run. - `sip_uri` string, nullable: SIP URI, e.g. sip:user@domain.com. - `sip_originating_region` 'us-east' | 'us-west' | 'null', nullable: Optional Twilio SIP region for direct SIP runs: us-east uses us1 and us-west uses us2. Null keeps Twilio's provider default. * `us-east` - US East * `us-west` - US West - `sip_auth` unknown - `websocket_url` string, nullable: Raw-PCM (16kHz 16-bit mono) websocket endpoint Cekura dials to run the whole call over a websocket you host, e.g. wss://your-host/voice. - `websocket_auth` unknown - `outbound_numbers` string[]: Phone numbers authorized for outbound calls (E.164 format). Example: `["+14155551234", "+14155550000"]` - `provider` SchemaAgentProviderCreate - `type` 'vapi' | 'retell' | 'elevenlabs' | 'agentforce' | 'cisco' | 'bland' | 'livekit' | 'pipecat' | 'synthflow' | 'agora' | 'koreai' | 'genesys' | 'amazon_connect' | 'telnyx' | 'gemini_cx' | 'assemblyai' | 'smallest' | 'custom' | '': Voice/inbound platform provider type. Valid values: vapi, retell, elevenlabs, bland, livekit, cisco, gemini_cx, smallest, synthflow, koreai, genesys, amazon_connect, pipecat, custom. Use 'custom' (or omit) for chat-only agents with no voice provider — the chat channel goes in chat_agent_details.type. For a raw-PCM websocket voice agent you host yourself, use type='custom' and put the endpoint in telephony.websocket_url. Text-only channels (sms, whatsapp, agentforce, sierra) belong in chat_agent_details.type, not here. * `vapi` - Vapi * `retell` - Retell * `elevenlabs` - Elevenlabs * `agentforce` - Agentforce * `cisco` - Cisco * `bland` - Bland * `livekit` - Livekit * `pipecat` - Pipecat * `synthflow` - Synthflow * `agora` - Agora * `koreai` - Koreai * `genesys` - Genesys * `amazon_connect` - Amazon Connect * `telnyx` - Telnyx * `gemini_cx` - Gemini Enterprise CX * `assemblyai` - AssemblyAI * `smallest` - Smallest AI * `custom` - Custom (chat-only, no voice provider) - `agent_id` string, nullable: Agent ID for voice/inbound runs on the provider's platform. For vapi, elevenlabs, retell, synthflow, telnyx, assemblyai, smallest, and bland this is the voice agent ID (for bland it's the persona_id). Bland's pathway_id and retell's chat agent ID go in chat_agent_details.config.agent_id. - `credentials` AgentCredentials: Nested credentials block inside the provider object. - `api_key` string: API key or client secret for the provider (write-only — never returned). Required for: vapi, retell, elevenlabs, bland, livekit, pipecat, synthflow, telnyx, assemblyai, smallest. koreai and genesys use their client secret (passed as api_key); cisco only when using a customer-owned Service App. Not needed for: self_hosted, gemini_cx (Cekura impersonates config.service_account_email; no key). - `config` union - VapiConfig: VAPI provider configuration. - `public_key` string: VAPI Public Key for WebRTC sessions only. Not required for telephony or chat testing. - `trigger_url` string: URL Cekura calls to create outbound VAPI phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - RetellConfig: Retell provider configuration. - `trigger_url` string: URL Cekura calls to create outbound Retell phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - ElevenLabsConfig: ElevenLabs provider configuration. - `trigger_url` string: URL Cekura calls to create outbound ElevenLabs phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - `elevenlabs_region` 'us' | 'eu': ElevenLabs API region. 'us' uses api.elevenlabs.io, 'eu' uses api.eu.residency.elevenlabs.io. Defaults to 'us'. * `us` - us * `eu` - eu - `elevenlabs_base_url_override` string: Optional custom base URL for ElevenLabs API. Takes precedence over elevenlabs_region if set. - `elevenlabs_environment` string: ElevenLabs environment used to resolve the agent's environment variables (tool URLs, secrets, headers) on test runs, e.g. test. Must match an environment configured in ElevenLabs. Omit or send blank to use production. - `elevenlabs_branch_id` string: ElevenLabs agent branch to run conversations against. Omit or send blank to use the agent's default branch. - BlandConfig: Bland AI provider configuration. - `encrypted_key` string: Twilio credential bundle for Bland outbound calls. Required when using Bland with Twilio telephony. - LiveKitConfig: LiveKit provider configuration. - `api_secret` string, required: LiveKit API secret. Required alongside api_key. - `url` string, required: LiveKit server WebSocket URL, e.g. wss://acme.livekit.cloud. - `agent_name` string: LiveKit agent name to connect to. - `config` unknown - `tracing_enabled` boolean: Enable LiveKit tracing (requires Cekura SDK integrated in your LiveKit agent). - `trigger_url` string: URL Cekura calls to create outbound phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - SynthflowConfig: Synthflow provider configuration. - `synthflow_base_url_override` string: Optional custom base URL for Synthflow API, e.g. for EU residency. Leave empty to use the default endpoint. - KoreAiConfig: Kore.ai provider configuration. XO platform (default) uses api_key + client_id + bot_id; the Artemis agent platform uses the artemis_* keys. Both sets can be stored side by side; platform selects the active one. - `platform` 'xo' | 'artemis': Kore product the agent runs on: "xo" (default) or "artemis". * `xo` - xo * `artemis` - artemis - `client_id` string: KoreAI OAuth2 Client ID. XO platform. - `bot_id` string: KoreAI Bot ID to connect to. XO platform. - `host` string: KoreAI XO host. Defaults to bots.kore.ai. - `artemis_api_key` string: Artemis project-bound x-api-key. Encrypted at rest; returned as artemis_api_key_configured. - `artemis_host` string: Artemis host, e.g. ind-agents.kore.ai. - `artemis_project_id` string: Artemis project ID the API key is bound to. - GenesysConfig: Genesys Cloud provider configuration. - `client_id` string, required: Genesys Cloud OAuth2 Client ID. - `region` string, required: Genesys Cloud region, e.g. us-east-1. - CiscoConfig: Cisco Webex Contact Center provider configuration. - `org_id` string, required: Control Hub organization UUID of the contact center tenant. - `region` string: Contact Center datacenter, e.g. us1, eu1, anz1. Defaults to us1. - `client_id` string: Service App client ID (pair with the client secret and refresh_token). - `refresh_token` string: Service App refresh token; stored encrypted. - GeminiEnterpriseCxConfig: Gemini Enterprise CX (Google CX Agent Studio) provider configuration. No API key: Cekura impersonates the reader service account. - `service_account_email` string, required: Your reader service account (name@project.iam.gserviceaccount.com) that Cekura's per-agent identity is allowed to act as. - `project_id` string: GCP project that hosts the agent. Defaults to the project named in the service-account email. - `location` string, required: Agent region, e.g. us-central1 or global. The CX agent id goes in provider.agent_id. - AssemblyAIConfig: AssemblyAI Voice Agent API provider configuration. The API key goes in credentials.api_key, the agent id in provider.agent_id. - `region` 'us' | 'eu': AssemblyAI deployment the agent lives in. Defaults to us (phone agents are US-hosted). * `us` - us * `eu` - eu - PipecatConfig: Pipecat provider configuration. - `pipecat_agent_name` string: Name of the Pipecat agent. Required when tracing_enabled is false. - `config` unknown - `room_properties` unknown - `webhook_url` string: Webhook URL for Pipecat call events. - `tracing_enabled` boolean: Enable Pipecat tracing (requires Cekura SDK integrated in your Pipecat agent). When true, pipecat_agent_name is not required. - SelfHostedConfig: Self-hosted provider configuration. - `send_post_conversation_metadata` boolean: Enable Cekura to accept call transcripts pushed by your agent via POST /custom-provider-webhook/. Set to true when your agent sends its own transcripts to Cekura after each call. - `trigger_url` string: URL Cekura calls to create outbound phone calls. Required to enable auto_dial_outbound for the custom provider; must answer 2xx within 30s. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - AmazonConnectConfig: Amazon Connect provider configuration. - `widget_id` string: Chat widget UUID from the Amazon Connect console. - `snippet_id` string: Base64-encoded KMS snippet from your Amazon Connect chat widget. - `connect_host` string: Amazon Connect instance host, e.g. acme.my.connect.aws. - `region` string: AWS region for the Connect instance. Defaults to us-east-1. - `chat_agent_details` ChatAgentDetails: Chat-mode provider configuration nested inside the provider block. - `type` 'retell' | 'bland' | 'vapi' | 'elevenlabs' | 'livekit' | 'agora' | 'pipecat' | 'sms' | 'whatsapp' | 'self_hosted' | 'agentforce' | 'amazon_connect' | 'koreai' | 'sierra' | '': Chat provider type. Must be compatible with the voice provider.type. Valid values: retell, bland, vapi, elevenlabs, livekit, agora, sms, whatsapp, self_hosted, agentforce, amazon_connect, koreai, sierra. Pass an empty string "" (or send chat_agent_details: null) to clear the chat overlay. * `retell` - retell * `bland` - bland * `vapi` - vapi * `elevenlabs` - elevenlabs * `livekit` - livekit * `agora` - agora * `pipecat` - pipecat * `sms` - sms * `whatsapp` - whatsapp * `self_hosted` - self_hosted * `agentforce` - agentforce * `amazon_connect` - amazon_connect * `koreai` - koreai * `sierra` - sierra - `config` union - RetellChatConfig: Retell chat configuration. - `agent_id` string: The Retell chat agent ID to use for text-mode test runs. Optional — when omitted, a temporary chat agent is cloned from the voice agent for each run. - BlandChatConfig: Bland chat configuration. - `agent_id` string, required: The Bland pathway_id to use for text-mode test runs. - AgentforceChatConfig: Agentforce (Salesforce) chat configuration. - `client_secret` string, required: OAuth2 client secret for Salesforce authentication. - `client_id` string, required: OAuth2 client ID for Salesforce authentication. - `domain` string, required: Salesforce domain, e.g. https://example.sandbox.my.salesforce.com. - `agent_id` string, required: Agentforce agent ID (0Xx...). - SelfHostedChatConfig: Self-hosted websocket chat configuration. - `url` string, required: WebSocket endpoint URL (wss://) to connect for text-mode test runs. - `headers` object: Optional headers to send on the WebSocket upgrade request, e.g. {"Authorization": "Bearer token"}. - `websocket_secret` string: Secret sent as the X-VOCERA-SECRET header on the WebSocket upgrade (write-only — masked in responses). - AmazonConnectChatConfig: Amazon Connect chat-widget configuration. - `widget_id` string, required: Chat-widget UUID from the Amazon Connect console. - `snippet_id` string, required: Base64-encoded KMS snippet from your Amazon Connect chat widget. - `connect_host` string, required: Amazon Connect instance host, e.g. acme.my.connect.aws. - `region` string: AWS region for the Connect instance. Defaults to us-east-1. - KoreAiChatConfig: Kore.ai XO chat configuration. - `api_secret` string: Kore XO Web/Mobile Client API key. Encrypted at rest. - `api_secret_configured` boolean: Whether the Kore XO Web/Mobile Client API key is configured. - `host` string: Kore XO host. Defaults to platform.kore.ai. - `rtm_signing_public_key` string: Optional Kore secure-RTM ECDSA P-256 public-key PEM used to verify the provider handshake. - `allow_unverified_secure_rtm` boolean: Allow secure RTM without a signing-key pin. Defaults to true for existing credentials; set false to require rtm_signing_public_key. - SierraChatConfig: Sierra chat configuration. - `agent_token` string, required: Sierra Headless API agent token (write-only — masked in responses). - `host` string: Sierra API host. Defaults to api.sierra.chat; customer-specific hosts differ. - `api_secret` string: Bearer API key, only needed when the Sierra org enforces Headless API authentication (write-only — masked in responses). - `chat_provider` string: Read-only. The provider that runs this agent's text-mode conversations. Mirrors chat_agent_details.type when that block is present, and is also reported for chat-only agents whose chat runtime is a voice platform, where chat_agent_details is omitted. Set the chat provider via chat_agent_details. - `auto_dial_outbound` boolean, nullable: Auto-dial the outbound number when running outbound scenarios. Supported for: vapi, retell, elevenlabs, bland, livekit. - `auto_import_calls` boolean, nullable: Auto-import calls from the provider every 30s. Supported for: vapi, retell, elevenlabs. - `auto_sync_prompt` boolean, nullable: Enable one-way prompt sync from the provider to Cekura on a schedule. Cekura re-fetches the provider prompt and updates the agent description; it does not push Cekura description changes back to the provider. Supported for: vapi, retell, elevenlabs, synthflow, telnyx, bland. - `send_post_conversation_metadata` boolean, nullable: Enable Cekura to accept call transcripts pushed by your agent via POST /custom-provider-webhook/. Only for self-hosted (custom) providers. - `redact_fields` string[], nullable: Sensitive fields removed from the transcript and audio of every call ingested for this agent, including auto-imported and webhook calls. Empty list disables redaction. Billed at 0.1 credits per call minute by default whenever any field is set. - `configure_from_provider` boolean: When true on create for a cloud provider (vapi/retell/elevenlabs/synthflow), Cekura fetches the assistant's prompt, settings, phone, tools, dynamic variables and knowledge base and configures the agent automatically. Requires agent_id + credentials.api_key. The create response includes a progress_id to poll import-progress/. - `enabled_connections` string[]: Transports an evaluator run can use against this agent, as accepted by the unified run endpoint's `transport` field. Omitted from list responses. - `agent_speaks_first` boolean, nullable: True = agent speaks first; False = test user speaks first; null = auto-detect. - `predefined_metrics` unknown - `knowledge_base_files` AgentKnowledgeBaseFileWrite[]: Full desired set of knowledge base files. Reference existing by `id`; add new ones with `file_name` + `content_base64`. Omitted existing files are deleted. - `id` integer: ID of an existing file to keep. Files omitted from the list are deleted. - `file_name` string: Name for a new file, including extension (pdf, txt, json, csv, xml, md). - `name` string: Alias for file_name. - `content_base64` string: Base64-encoded content for a new file. A data-URI prefix is accepted. - `enabled_personalities` integer[]: 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. Write-only — never returned in API responses. Use `webhook_secret_configured` to check whether one is set. - `webhook_secret_configured` string - `mock_tools` AgentMockToolWrite[]: 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. - `id` integer: ID of an existing mock tool to update. Omit to create a new tool (or update by matching name). - `name` string: Tool name. Required for new tools. Alphanumerics, underscores and hyphens only; under 64 characters. - `description` string: What the tool does. - `mock_data` unknown - `freetext_params` string[]: Parameter names skipped during mock matching because they are free-text (e.g. ["notes", "reason"]). - `served_via` AgentMockToolServedViaWrite: Runtime routing for a mock tool on write (request side of `mock_tools[].served_via`). - `type` 'direct' | 'mcp': 'direct' = per-tool webhook URL (default). 'mcp' = served through an MCP endpoint; requires mock_index. * `direct` - direct * `mcp` - mcp - `mock_index` integer: MCP endpoint index (1-based). Tools sharing an index are served by the same MCP endpoint. Required when type='mcp'. - `mock_tools_enabled` boolean: Whether mock tools should be selected by default when configuring a run. - `mock_tools_provider` string, nullable: Provider the mock tools were fetched from (vapi, retell, elevenlabs, custom). Null until auto-fetch has been run. - `dynamic_variables` AgentDynamicVariableWrite[]: Full desired set of dynamic variable definitions, matched by name. Omitted existing variables are deleted. - `id` integer: Ignored on write — variables are matched by name. - `name` string, required: Variable name exactly as it appears in the agent context. - `description` string, required: What the variable represents and its expected format. - `created_at` string, date-time: Timestamp when the agent was created Example: `"2021-01-01T00:00:00Z"` - `updated_at` string, date-time: Timestamp when the agent was last updated Example: `"2021-01-01T00:00:00Z"` - `email_id` string, email, nullable: Email address this agent receives at. When set, enables email-based test runs. ## Response `201` - AIAgentV2 - `id` integer: Agent ID. Example: `2142` - `name` string: Agent name. Optional when configure_from_provider is set — it's fetched from the provider. - `description` string, required: A detailed description of what this agent does and how it should interact Example: ```text AI agent for handling customer support inquiries and resolving technical issues ``` - `project` integer: The project this agent belongs to - `language` 'af' | 'ar' | 'bn' | 'bg' | 'zh' | 'cs' | 'da' | 'nl' | 'en' | 'et' | 'fi' | 'fr' | 'de' | 'el' | 'gu' | 'hi' | 'he' | 'hu' | 'id' | 'it' | 'ja' | 'kn' | 'kk' | 'ko' | 'ms' | 'ml' | 'mr' | 'multi' | 'no' | 'pl' | 'pa' | 'pt' | 'ro' | 'ru' | 'sk' | 'es' | 'sv' | 'th' | 'tr' | 'tl' | 'ta' | 'te' | 'uk' | 'uz' | 'vi': 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 * `kk` - Kazakh * `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 * `uz` - Uzbek * `vi` - Vietnamese - `telephony` AgentTelephony: Phone / SIP / websocket voice channel configuration for the agent. - `phone_number` string: The agent's own E.164 number, not a customer's: Cekura dials it for inbound tests, and the agent's outbound calls come from it. E.g. +14155551234. - `inbound` boolean: True = agent receives inbound calls; False = outbound only. A property of the agent, not of one run: never flip it to change who dials whom. To dial a different number in a run, pass `outbound_phone_number` to the run. - `sip_uri` string, nullable: SIP URI, e.g. sip:user@domain.com. - `sip_originating_region` 'us-east' | 'us-west' | 'null', nullable: Optional Twilio SIP region for direct SIP runs: us-east uses us1 and us-west uses us2. Null keeps Twilio's provider default. * `us-east` - US East * `us-west` - US West - `sip_auth` unknown - `websocket_url` string, nullable: Raw-PCM (16kHz 16-bit mono) websocket endpoint Cekura dials to run the whole call over a websocket you host, e.g. wss://your-host/voice. - `websocket_auth` unknown - `outbound_numbers` string[]: Phone numbers authorized for outbound calls (E.164 format). Example: `["+14155551234", "+14155550000"]` - `provider` AgentProvider - `type` 'vapi' | 'retell' | 'elevenlabs' | 'agentforce' | 'cisco' | 'bland' | 'livekit' | 'pipecat' | 'synthflow' | 'agora' | 'koreai' | 'genesys' | 'amazon_connect' | 'telnyx' | 'gemini_cx' | 'assemblyai' | 'smallest' | 'custom' | '': Voice/inbound platform provider type. Valid values: vapi, retell, elevenlabs, bland, livekit, cisco, gemini_cx, smallest, synthflow, koreai, genesys, amazon_connect, pipecat, custom. Use 'custom' (or omit) for chat-only agents with no voice provider — the chat channel goes in chat_agent_details.type. For a raw-PCM websocket voice agent you host yourself, use type='custom' and put the endpoint in telephony.websocket_url. Text-only channels (sms, whatsapp, agentforce, sierra) belong in chat_agent_details.type, not here. * `vapi` - Vapi * `retell` - Retell * `elevenlabs` - Elevenlabs * `agentforce` - Agentforce * `cisco` - Cisco * `bland` - Bland * `livekit` - Livekit * `pipecat` - Pipecat * `synthflow` - Synthflow * `agora` - Agora * `koreai` - Koreai * `genesys` - Genesys * `amazon_connect` - Amazon Connect * `telnyx` - Telnyx * `gemini_cx` - Gemini Enterprise CX * `assemblyai` - AssemblyAI * `smallest` - Smallest AI * `custom` - Custom (chat-only, no voice provider) - `agent_id` string, nullable: Agent ID for voice/inbound runs on the provider's platform. For vapi, elevenlabs, retell, synthflow, telnyx, assemblyai, smallest, and bland this is the voice agent ID (for bland it's the persona_id). Bland's pathway_id and retell's chat agent ID go in chat_agent_details.config.agent_id. - `credentials` AgentCredentials: Nested credentials block inside the provider object. - `api_key` string: API key or client secret for the provider (write-only — never returned). Required for: vapi, retell, elevenlabs, bland, livekit, pipecat, synthflow, telnyx, assemblyai, smallest. koreai and genesys use their client secret (passed as api_key); cisco only when using a customer-owned Service App. Not needed for: self_hosted, gemini_cx (Cekura impersonates config.service_account_email; no key). - `config` union - VapiConfig: VAPI provider configuration. - `public_key` string: VAPI Public Key for WebRTC sessions only. Not required for telephony or chat testing. - `trigger_url` string: URL Cekura calls to create outbound VAPI phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - RetellConfig: Retell provider configuration. - `trigger_url` string: URL Cekura calls to create outbound Retell phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - ElevenLabsConfig: ElevenLabs provider configuration. - `trigger_url` string: URL Cekura calls to create outbound ElevenLabs phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - `elevenlabs_region` 'us' | 'eu': ElevenLabs API region. 'us' uses api.elevenlabs.io, 'eu' uses api.eu.residency.elevenlabs.io. Defaults to 'us'. * `us` - us * `eu` - eu - `elevenlabs_base_url_override` string: Optional custom base URL for ElevenLabs API. Takes precedence over elevenlabs_region if set. - `elevenlabs_environment` string: ElevenLabs environment used to resolve the agent's environment variables (tool URLs, secrets, headers) on test runs, e.g. test. Must match an environment configured in ElevenLabs. Omit or send blank to use production. - `elevenlabs_branch_id` string: ElevenLabs agent branch to run conversations against. Omit or send blank to use the agent's default branch. - BlandConfig: Bland AI provider configuration. - `encrypted_key` string: Twilio credential bundle for Bland outbound calls. Required when using Bland with Twilio telephony. - LiveKitConfig: LiveKit provider configuration. - `api_secret` string, required: LiveKit API secret. Required alongside api_key. - `url` string, required: LiveKit server WebSocket URL, e.g. wss://acme.livekit.cloud. - `agent_name` string: LiveKit agent name to connect to. - `config` unknown - `tracing_enabled` boolean: Enable LiveKit tracing (requires Cekura SDK integrated in your LiveKit agent). - `trigger_url` string: URL Cekura calls to create outbound phone calls. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - SynthflowConfig: Synthflow provider configuration. - `synthflow_base_url_override` string: Optional custom base URL for Synthflow API, e.g. for EU residency. Leave empty to use the default endpoint. - KoreAiConfig: Kore.ai provider configuration. XO platform (default) uses api_key + client_id + bot_id; the Artemis agent platform uses the artemis_* keys. Both sets can be stored side by side; platform selects the active one. - `platform` 'xo' | 'artemis': Kore product the agent runs on: "xo" (default) or "artemis". * `xo` - xo * `artemis` - artemis - `client_id` string: KoreAI OAuth2 Client ID. XO platform. - `bot_id` string: KoreAI Bot ID to connect to. XO platform. - `host` string: KoreAI XO host. Defaults to bots.kore.ai. - `artemis_api_key` string: Artemis project-bound x-api-key. Encrypted at rest; returned as artemis_api_key_configured. - `artemis_host` string: Artemis host, e.g. ind-agents.kore.ai. - `artemis_project_id` string: Artemis project ID the API key is bound to. - GenesysConfig: Genesys Cloud provider configuration. - `client_id` string, required: Genesys Cloud OAuth2 Client ID. - `region` string, required: Genesys Cloud region, e.g. us-east-1. - CiscoConfig: Cisco Webex Contact Center provider configuration. - `org_id` string, required: Control Hub organization UUID of the contact center tenant. - `region` string: Contact Center datacenter, e.g. us1, eu1, anz1. Defaults to us1. - `client_id` string: Service App client ID (pair with the client secret and refresh_token). - `refresh_token` string: Service App refresh token; stored encrypted. - GeminiEnterpriseCxConfig: Gemini Enterprise CX (Google CX Agent Studio) provider configuration. No API key: Cekura impersonates the reader service account. - `service_account_email` string, required: Your reader service account (name@project.iam.gserviceaccount.com) that Cekura's per-agent identity is allowed to act as. - `project_id` string: GCP project that hosts the agent. Defaults to the project named in the service-account email. - `location` string, required: Agent region, e.g. us-central1 or global. The CX agent id goes in provider.agent_id. - AssemblyAIConfig: AssemblyAI Voice Agent API provider configuration. The API key goes in credentials.api_key, the agent id in provider.agent_id. - `region` 'us' | 'eu': AssemblyAI deployment the agent lives in. Defaults to us (phone agents are US-hosted). * `us` - us * `eu` - eu - PipecatConfig: Pipecat provider configuration. - `pipecat_agent_name` string: Name of the Pipecat agent. Required when tracing_enabled is false. - `config` unknown - `room_properties` unknown - `webhook_url` string: Webhook URL for Pipecat call events. - `tracing_enabled` boolean: Enable Pipecat tracing (requires Cekura SDK integrated in your Pipecat agent). When true, pipecat_agent_name is not required. - SelfHostedConfig: Self-hosted provider configuration. - `send_post_conversation_metadata` boolean: Enable Cekura to accept call transcripts pushed by your agent via POST /custom-provider-webhook/. Set to true when your agent sends its own transcripts to Cekura after each call. - `trigger_url` string: URL Cekura calls to create outbound phone calls. Required to enable auto_dial_outbound for the custom provider; must answer 2xx within 30s. - `trigger_secret` string: Optional shared secret sent as the X-CEKURA-SECRET header on trigger URL requests, so your endpoint can reject calls it didn't expect. Write-only — responses expose trigger_secret_configured instead. - AmazonConnectConfig: Amazon Connect provider configuration. - `widget_id` string: Chat widget UUID from the Amazon Connect console. - `snippet_id` string: Base64-encoded KMS snippet from your Amazon Connect chat widget. - `connect_host` string: Amazon Connect instance host, e.g. acme.my.connect.aws. - `region` string: AWS region for the Connect instance. Defaults to us-east-1. - `chat_agent_details` ChatAgentDetails: Chat-mode provider configuration nested inside the provider block. - `type` 'retell' | 'bland' | 'vapi' | 'elevenlabs' | 'livekit' | 'agora' | 'pipecat' | 'sms' | 'whatsapp' | 'self_hosted' | 'agentforce' | 'amazon_connect' | 'koreai' | 'sierra' | '': Chat provider type. Must be compatible with the voice provider.type. Valid values: retell, bland, vapi, elevenlabs, livekit, agora, sms, whatsapp, self_hosted, agentforce, amazon_connect, koreai, sierra. Pass an empty string "" (or send chat_agent_details: null) to clear the chat overlay. * `retell` - retell * `bland` - bland * `vapi` - vapi * `elevenlabs` - elevenlabs * `livekit` - livekit * `agora` - agora * `pipecat` - pipecat * `sms` - sms * `whatsapp` - whatsapp * `self_hosted` - self_hosted * `agentforce` - agentforce * `amazon_connect` - amazon_connect * `koreai` - koreai * `sierra` - sierra - `config` union - RetellChatConfig: Retell chat configuration. - `agent_id` string: The Retell chat agent ID to use for text-mode test runs. Optional — when omitted, a temporary chat agent is cloned from the voice agent for each run. - BlandChatConfig: Bland chat configuration. - `agent_id` string, required: The Bland pathway_id to use for text-mode test runs. - AgentforceChatConfig: Agentforce (Salesforce) chat configuration. - `client_secret` string, required: OAuth2 client secret for Salesforce authentication. - `client_id` string, required: OAuth2 client ID for Salesforce authentication. - `domain` string, required: Salesforce domain, e.g. https://example.sandbox.my.salesforce.com. - `agent_id` string, required: Agentforce agent ID (0Xx...). - SelfHostedChatConfig: Self-hosted websocket chat configuration. - `url` string, required: WebSocket endpoint URL (wss://) to connect for text-mode test runs. - `headers` object: Optional headers to send on the WebSocket upgrade request, e.g. {"Authorization": "Bearer token"}. - `websocket_secret` string: Secret sent as the X-VOCERA-SECRET header on the WebSocket upgrade (write-only — masked in responses). - AmazonConnectChatConfig: Amazon Connect chat-widget configuration. - `widget_id` string, required: Chat-widget UUID from the Amazon Connect console. - `snippet_id` string, required: Base64-encoded KMS snippet from your Amazon Connect chat widget. - `connect_host` string, required: Amazon Connect instance host, e.g. acme.my.connect.aws. - `region` string: AWS region for the Connect instance. Defaults to us-east-1. - KoreAiChatConfig: Kore.ai XO chat configuration. - `api_secret` string: Kore XO Web/Mobile Client API key. Encrypted at rest. - `api_secret_configured` boolean: Whether the Kore XO Web/Mobile Client API key is configured. - `host` string: Kore XO host. Defaults to platform.kore.ai. - `rtm_signing_public_key` string: Optional Kore secure-RTM ECDSA P-256 public-key PEM used to verify the provider handshake. - `allow_unverified_secure_rtm` boolean: Allow secure RTM without a signing-key pin. Defaults to true for existing credentials; set false to require rtm_signing_public_key. - SierraChatConfig: Sierra chat configuration. - `agent_token` string, required: Sierra Headless API agent token (write-only — masked in responses). - `host` string: Sierra API host. Defaults to api.sierra.chat; customer-specific hosts differ. - `api_secret` string: Bearer API key, only needed when the Sierra org enforces Headless API authentication (write-only — masked in responses). - `chat_provider` string: Read-only. The provider that runs this agent's text-mode conversations. Mirrors chat_agent_details.type when that block is present, and is also reported for chat-only agents whose chat runtime is a voice platform, where chat_agent_details is omitted. Set the chat provider via chat_agent_details. - `auto_dial_outbound` boolean, nullable: Auto-dial the outbound number when running outbound scenarios. Supported for: vapi, retell, elevenlabs, bland, livekit. - `auto_import_calls` boolean, nullable: Auto-import calls from the provider every 30s. Supported for: vapi, retell, elevenlabs. - `auto_sync_prompt` boolean, nullable: Enable one-way prompt sync from the provider to Cekura on a schedule. Cekura re-fetches the provider prompt and updates the agent description; it does not push Cekura description changes back to the provider. Supported for: vapi, retell, elevenlabs, synthflow, telnyx, bland. - `send_post_conversation_metadata` boolean, nullable: Enable Cekura to accept call transcripts pushed by your agent via POST /custom-provider-webhook/. Only for self-hosted (custom) providers. - `redact_fields` string[], nullable: Sensitive fields removed from the transcript and audio of every call ingested for this agent, including auto-imported and webhook calls. Empty list disables redaction. Billed at 0.1 credits per call minute by default whenever any field is set. - `enabled_connections` string[]: Transports an evaluator run can use against this agent, as accepted by the unified run endpoint's `transport` field. Omitted from list responses. - `agent_speaks_first` boolean, nullable: True = agent speaks first; False = test user speaks first; null = auto-detect. - `predefined_metrics` unknown - `knowledge_base_files` KnowledgeBaseFile[]: Knowledge base files attached to the agent. - `id` integer - `agent` integer, required - `file` string, uri, required: Knowledge base file - `file_url` string: URL of the Knowledge file - `file_name` string: Name of the Knowledge file - `file_type` string: MIME type of the Knowledge file - `file_size` integer: Size in bytes. Example: `1048576` - `created_at` string, date-time: When this record was created. Example: `2024-03-15T10:30:45Z` - `updated_at` string, date-time: When this record was last updated. Example: `2024-03-15T10:35:11Z` - `enabled_personalities` integer[]: 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. Write-only — never returned in API responses. Use `webhook_secret_configured` to check whether one is set. - `webhook_secret_configured` string - `mock_tools` AgentMockToolRead[]: Mock tools registered on the agent, each with its mock data and runtime access (served_via). - `id` integer, required - `name` string, required - `description` string, required - `mock_data` unknown, required - `served_via` AgentMockToolServedVia, required: How a mock tool is reached at runtime (response side of `mock_tools[].served_via`). - `type` 'direct' | 'mcp', required: 'direct' = per-tool webhook URL; 'mcp' = served through the agent's MCP endpoint. * `direct` - direct * `mcp` - mcp - `url` string, required: Runtime URL the agent calls to reach this tool. - `mock_index` integer: MCP endpoint index. Present only when type='mcp'. - `mcp_server` unknown - `subscriber_count` integer: Number of agents in the project using this tool. - `is_shared` boolean: True when more than one agent uses this tool, so an edit affects all of them. - `mock_tools_enabled` boolean: Whether mock tools should be selected by default when configuring a run. - `mock_tools_provider` string, nullable: Provider the mock tools were fetched from (vapi, retell, elevenlabs, custom). Null until auto-fetch has been run. - `dynamic_variables` AgentDynamicVariableRead[]: Dynamic variable definitions for the agent, ordered by name. - `id` integer, required - `name` string, required - `description` string, required - `created_at` string, date-time: Timestamp when the agent was created Example: `"2021-01-01T00:00:00Z"` - `updated_at` string, date-time: Timestamp when the agent was last updated Example: `"2021-01-01T00:00:00Z"` - `email_id` string, email, nullable: Email address this agent receives at. When set, enables email-based test runs. ## Other responses - `202` - `400` ## Changes - **2026-11-03** `a6fb6a739212`: 1 info - endpoint added [Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/test_framework/v2/aiagents/post.md) --- [API](https://skmtc.dev/cekura/apis/cekura-api.md) - [All operations](https://skmtc.dev/cekura/apis/cekura-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cekura/apis/cekura-api/revisions/a6fb6a739212?raw)