Retell AI

List all available voices. Returns voice IDs, names, provider, gender, accent, age, and preview audio URLs. Use this to find a voice_id for creating agents.

Get details for a specific voice including provider, gender, accent, age, and preview audio URL.

List all voice agents. Returns agent IDs, names, versions, voice and response engine configuration. Supports pagination.

Get full configuration for a voice agent including voice settings, response engine, webhook, call handling, voicemail, analysis prompts, and all behavioral parameters.

List all Retell LLM response engines. These contain the prompts, tools (including transfer_call), states, and begin_message that power voice agents.

Get full details for a Retell LLM response engine including general_prompt, begin_message, tools (transfer_call, end_call, etc.), states, model settings, and knowledge base IDs.

List all conversation flows. Returns flow IDs, versions, global prompts, nodes, and tool configurations.

Get a conversation flow's full configuration including global prompt, nodes (conversation, transfer, branch, end, SMS, etc.), tools, and model settings.

List calls with filtering by agent, status, phone number, date range, sentiment, direction, and more. Returns transcripts, recordings, analysis, cost, and latency. Supports pagination up to 1000 per page.

Get full call details including transcript, transcript with tool calls, recording URL, call analysis (summary, sentiment, success, custom data), latency metrics, cost breakdown, disconnection reason, and transfer destination.

List all phone numbers including type (retell-twilio, retell-telnyx, custom), bound inbound/outbound agents, nicknames, country restrictions, and webhook URLs.

Get full details for a phone number including bound agents, nickname, country restrictions, webhook URL, SIP config, and fallback number.

List all knowledge bases with IDs, names, processing status, chunk settings, sources, and auto-refresh configuration.

Get full details for a knowledge base including status, chunk config, all sources (documents, texts, URLs), and auto-refresh settings.

Get your current and maximum concurrency — how many simultaneous calls are active and how many your plan allows. Useful for monitoring capacity before launching batch campaigns.

Create a new voice agent. Requires a voice_id and response_engine. The response_engine connects to a Retell LLM (llm_id), custom LLM (websocket URL), or conversation flow (conversation_flow_id). Configure voice behavior, call handling, voicemail, analysis, and more.

Update a voice agent's configuration. Only include fields you want to change. Same parameters as create_agent plus agent_id.

Publish the latest draft version of an agent. Creates a new draft with a higher version number. Published versions are used for live calls.

Create a Retell LLM response engine with prompts, tools, and conversation states. This is where you define the agent's instructions, begin_message, and tools like transfer_call for live transfers. Attach to an agent via create_agent or update_agent.

Update a Retell LLM response engine. Change prompts, begin_message, tools, states, model, or knowledge bases. Only include fields to change.

Create a conversation flow with nodes for structured multi-step calls. Node types: conversation, end, function, transfer_call, branch, press_digit, sms, extract_dynamic_variables, agent_swap, bridge_transfer, cancel_transfer. Attach to an agent via response_engine.

Update a conversation flow's nodes, global prompt, tools, model, or knowledge bases. Only include fields to change.

Make an outbound phone call immediately. The call uses the agent bound to the from_number, or specify override_agent_id. Inject dynamic variables into the agent's prompt for personalization.

Create a batch of outbound calls. Calls can be scheduled or sent immediately. Each task in the batch can have its own dynamic variables and metadata for personalization. Use for campaigns, lead calling, appointment reminders.

Update an existing call's metadata, data storage settings, dynamic variable overrides, or custom attributes.

Purchase a new phone number. Specify area code, country, provider, and optionally bind inbound/outbound agents immediately. The number can be used for making and receiving AI-powered calls.

Update phone number configuration — change bound agents, nickname, webhook URL, country restrictions, or fallback number.

Create a knowledge base from text content and/or URLs. Attach to an LLM or conversation flow via knowledge_base_ids to give agents context during calls.

Add additional text content or URLs to an existing knowledge base without replacing existing sources.

Create a web-based call session. Returns a call_id and web_call_link for browser-based voice calls without a phone number. Useful for testing agents, embedding calls in web apps, or demos.

Import an existing phone number from your own Twilio or Telnyx account into Retell. You provide the phone number, your telephony credentials, and Retell configures it for AI calling.

Delete a voice agent by ID. Deletes all versions of the agent.

Delete a Retell LLM response engine. Deletes all versions.

Delete a conversation flow by ID.

Delete a call record by ID.

Release and delete a phone number. The number can no longer receive or make calls.

Delete a specific source from a knowledge base by source ID.

Delete a knowledge base and all its sources.