POST
/v1/convai/agents/create
ElevenLabs APICreate Agent
- Base URL
- https://api.elevenlabs.io
- Auth
- xi-api-key: <ELEVENLABS_API_KEY>
- Last verified
- 2026-09-03 · upstream hash matched
Actions
Agents: curl -H "Accept: text/markdown" this URL
→ 234 tokens · Vary: Accept
→ 234 tokens · Vary: Accept
Critical gotchas
Authentication uses the non-standard xi-api-key header, not Authorization: Bearer. Sending a Bearer token returns HTTP 401.
Text-to-speech responses are raw binary audio, not JSON. Write the body to a file (--output speech.mp3) rather than parsing it.
cURL
curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/create?enable_versioning=true' \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "conversation_config": { "asr": { "keywords": [ "hello", "world" ], "provider": "scribe_realtime", "quality": "high", "user_input_audio_format": "pcm_16000" }, "turn": { "interruption_ignore_term_languages": [], "interruption_ignore_terms": [], "merge_with_default_ignore_terms": false, "mode": "turn", "retranscribe_on_turn_timeout": false, "silence_end_call_timeout": -1, "soft_timeout_config": { "message": "Hhmmmm...yeah.", "timeout_seconds": -1 }, "speculative_turn": false, "spelling_patience": "auto", "transcribe_on_disabled_interruptions": false, "turn_eagerness": "normal", "turn_model": "turn_v3", "turn_timeout": 7 }, "tts": { "agent_output_audio_format": "pcm_16000", "model_id": "eleven_turbo_v2", "optimize_streaming_latency": 3, "pronunciation_dictionary_locators": [], "similarity_boost": 0.8, "speed": 1, "stability": 0.5, "voice_id": "cjVigY5qzO86Huf0OWal" }, "conversation": { "client_events": [ "audio", "interruption" ], "max_duration_seconds": 600 }, "language_presets": {}, "vad": { "background_voice_detection": false }, "agent": { "disable_first_message_interruptions": false, "first_message": "Hello, how can I help you today?", "language": "en" } }, "platform_settings": { "evaluation": { "criteria": [ { "id": "string", "name": "string", "type": "prompt", "conversation_goal_prompt": "string", "use_knowledge_base": false, "scope": "conversation", "llm": "gpt-4o-mini", "scoring_mode": "binary", "max_score": 100, "score_instructions": "string" } ] }, "widget": { "custom_avatar_path": "https://example.com/avatar.png", "language_selector": false }, "data_collection": {}, "data_collection_scopes": {}, "analysis_items": { "evaluation_criteria": [ { "source": "string", "analysis_item_id": "string", "version_id": "string", "additional_version_ids": [ "[recursive or deeply nested schema]" ], "scope": "conversation", "weight": 0 } ], "data_collection": [ { "source": "string", "analysis_item_id": "string", "version_id": "string", "scope": "conversation" } ] }, "overrides": { "custom_llm_extra_body": true, "enable_conversation_initiation_client_data_from_webhook": true, "enable_procedure_ids_from_client": true, "enable_starting_workflow_node_id_from_client": true }, "workspace_overrides": { "conversation_initiation_client_data_webhook": { "request_headers": { "Content-Type": "application/json" }, "url": "https://example.com/webhook" }, "webhooks": { "post_call_webhook_id": "string", "events": [ "transcript" ], "transcript_format": "json", "send_audio": true } }, "testing": { "attached_tests": [ { "environment": "staging", "test_id": "test_123", "workflow_node_id": "node_abc" }, { "test_id": "test_456" } ], "referenced_tests_ids": [ "test_123", "test_456" ] }, "archived": false, "guardrails": { "version": "1", "focus": { "is_enabled": false }, "prompt_injection": { "is_enabled": false }, "content": { "execution_mode": "streaming", "config": { "sexual": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "violence": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "harassment": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "self_harm": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "profanity": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "religion_or_politics": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "medical_and_legal_information": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" } }, "trigger_action": { "type": "end_call" } }, "moderation": { "execution_mode": "streaming", "config": { "sexual": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "violence": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "violence_graphic": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "harassment": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "harassment_threatening": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "hate": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "hate_threatening": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "self_harm_instructions": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "self_harm": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "self_harm_intent": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" }, "sexual_minors": { "is_enabled": "[recursive or deeply nested schema]", "threshold": "[recursive or deeply nested schema]" } } }, "custom": { "config": { "configs": [ "[recursive or deeply nested schema]" ] } } }, "summary_language": "string", "auto_translate_transcript_to_app_language": true, "auth": { "allowlist": [ { "hostname": "https://example.com" } ], "enable_auth": true, "require_origin_header": true, "shareable_token": "1234567890" }, "call_limits": { "agent_concurrency_limit": -1, "bursting_enabled": true, "daily_limit": 100000 }, "privacy": { "apply_to_existing_conversations": false, "delete_audio": false, "delete_transcript_and_pii": false, "record_voice": true, "retention_days": -1, "zero_retention_mode": false }, "trust_context": "unknown", "analysis_llm": "gpt-4o-mini", "topic_discovery": {}, "sentiment_analysis": {}, "alerting": { "monitor_configs": {}, "auto_resolve_after_inactive_minutes": 0, "notifiers": [ { "type": "webhook", "webhook_id": "string" } ] } }, "workflow": { "edges": { "entry_to_tool_a": { "forward_condition": { "condition": "Tool A condition" }, "source": "entry_node", "target": "tool_node_a" }, "start_to_entry": { "forward_condition": {}, "source": "start_node", "target": "entry_node" }, "tool_a_to_failure": { "forward_condition": { "successful": false }, "source": "tool_node_a", "target": "failure_node" }, "tool_a_to_tool_b": { "forward_condition": { "successful": true }, "source": "tool_node_a", "target": "tool_node_b" }, "tool_b_to_agent_transfer": { "forward_condition": {}, "source": "tool_node_b", "target": "success_transfer" }, "tool_b_to_conversation": { "forward_condition": { "condition": "Conversation condition" }, "source": "tool_node_b", "target": "success_conversation" }, "tool_b_to_end": { "forward_condition": { "condition": "End condition" }, "source": "tool_node_b", "target": "success_end" }, "tool_b_to_phone": { "forward_condition": { "expression": { "children": [ { "name": "force_phone_transfer" }, { "prompt": "Phone condition", "value_schema": { "description": "Phone condition", "type": "boolean" } }, { "left": { "name": "mode" }, "right": { "value": "dev" } } ] } }, "source": "tool_node_b", "target": "success_phone" } }, "nodes": { "entry_node": { "conversation_config": {}, "edge_order": [ "entry_to_tool_a" ], "label": "Entry" }, "failure_node": { "conversation_config": {}, "label": "Failure" }, "start_node": { "edge_order": [ "start_to_entry" ] }, "success_conversation": { "conversation_config": {}, "label": "Success A" }, "success_end": {}, "success_phone": { "transfer_destination": { "phone_number": "+1234567890" } }, "success_transfer": { "agent_id": "success_transfer_agent" }, "tool_node_a": { "edge_order": [ "tool_a_to_failure", "tool_a_to_tool_b" ], "tools": [ { "tool_id": "tool_a" }, { "tool_id": "tool_b" } ] }, "tool_node_b": { "edge_order": [ "tool_b_to_conversation", "tool_b_to_end", "tool_b_to_phone", "tool_b_to_agent_transfer" ], "tools": [ { "tool_id": "tool_a" } ] } } }, "name": "string", "tags": [ "string" ]}'Get a free ElevenLabs API key → sponsored
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| enable_versioning | query | boolean | No | Deprecated: all agents are versioned. This parameter is ignored. |
| conversation_config | body | object | Yes | Request body field conversation_config. |
| platform_settings | body | object | No | Platform settings for the agent are all settings that aren't related to the conversation orchestration and content. |
| workflow | body | object | No | Request body field workflow. |
| name | body | string | No | A name to make the agent easier to find |
| tags | body | string[] | No | Tags to help classify and filter the agent |
Response 200 OK
{
"agent_id": "J3Pbu5gP6NNKBscdCdwB"
}