CEcekura
test_framework

Retrieve an AI voice agent

Changed on

Retrieve an AI voice agent, including its configured connections.

Configured connection → run endpoint (call this before running scenarios; a run endpoint only works if its connection is configured on the agent):

  • telephony.phone_number → scenarios-run-voice
  • telephony.sip_uri → scenarios-run-sip
  • telephony.websocket_url → scenarios-run-chirp (raw-PCM voice websocket)
  • provider.type vapi / retell / livekit / pipecat / agora (WebRTC) → scenarios-run-vapi-webrtc / -retell-webrtc / -livekit-v2 / -pipecat-v2 / -agora
  • provider.type elevenlabs → scenarios-run-elevenlabs
  • provider.chat_agent_details (chat/SMS/WhatsApp) → scenarios-run-text
get/test_framework/v2/aiagents/{id}/

Request

  • Base URL
    https://api.cekura.ai
  • URL
    https://api.cekura.ai/test_framework/v2/aiagents/{id}/
  • Auth
    • API key in header X-CEKURA-API-KEY
    • or HTTP bearer
    • or HTTP bearer

Path parameters

idinteger required

A unique integer value identifying this ai agent.

Response

idinteger

Agent ID. Example: 2142

namestring

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

descriptionstring 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
projectinteger

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
enabled_connectionsstring[]

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_firstboolean nullable

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

predefined_metricsunknown
enabled_personalitiesinteger[]

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

webhook_urlstring uri

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

webhook_secretstring

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_configuredstring
mock_tools_enabledboolean

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

mock_tools_providerstring nullable

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

created_atstring date-time

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

updated_atstring date-time

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

email_idstring email nullable

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

Changes

  • a6fb6a739212Revision changes
    • info

      the endpoint scheme security oauth2 was added to the API

    • info

      the endpoint scheme security supabase_session was added to the API

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional write-only property predefined_metrics to the response with the status

    • info

      added the optional write-only property webhook_secret to the response with the status

    • info

      the response property became required for the status