apicheats.dev elevenlabs/llms.txt Raw .md
POST

/v1/convai/agents/create

ElevenLabs API

Create 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

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"
}