--- title: "Create Conversation" method: POST path: "/v1/convai/conversations" tags: ["Agents Platform"] --- # Create Conversation `POST /v1/convai/conversations` ## Request - Base URL: `https://api.elevenlabs.io` (the document declares no server; this is the origin it was published from) - URL: `https://api.elevenlabs.io/v1/convai/conversations` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a text conversation with an agent. This does not run the agent, and the agent sends no first message. This endpoint is in alpha and may change. ## Headers - `xi-api-key` string, nullable: Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website. ## Request body - CreateAgentConversationRequest - `agent` AgentMessagesPersistedAgent, required - `type` 'persisted', required - `agent_id` string, required - `branch_id` string, nullable: ID of the agent branch to use for this conversation - `overrides` AgentMessagesOverrides - `prompt` string, nullable: The prompt for the agent - `llm` 'gpt-4o-mini' | 'gpt-4o' | 'gpt-4' | 'gpt-4-turbo' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.2-chat-latest' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-6-astra' | 'gpt-6-sol' | 'gpt-6-luna' | 'gpt-6.1-sol' | 'gpt-6.1-terra' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-3.5-turbo' | 'gemini-1.5-pro' | 'gemini-1.5-flash' | 'gemini-2.0-flash' | 'gemini-2.0-flash-lite' | 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-pro-preview' | 'gemini-3.1-flash-lite-preview' | 'gemini-3.1-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite' | 'gemini-3.6-flash' | 'gemini-3.7-flash' | 'gemini-3.8-flash' | 'gemini-4-argon' | 'claude-sonnet-4-5' | 'claude-opus-4-6' | 'claude-opus-4-7' | 'claude-opus-4-8' | 'claude-opus-5' | 'claude-opus-5-5' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-sonnet-5-5' | 'claude-sonnet-4' | 'claude-haiku-4-5' | 'claude-haiku-5-5' | 'claude-3-7-sonnet' | 'claude-3-5-sonnet' | 'claude-3-5-sonnet-v1' | 'claude-3-haiku' | 'grok-beta' | 'custom-llm' | 'qwen3-4b' | 'qwen3-30b-a3b' | 'qwen36-35b-a3b' | 'qwen35-397b-a17b' | 'gpt-oss-20b' | 'gpt-oss-120b' | 'glm-45-air-fp8' | 'glm-52' | 'deepseek-v41-flash' | 'nemotron-35-super-vl-nvfp4' | 'gemini-2.5-flash-preview-09-2025' | 'gemini-2.5-flash-lite-preview-09-2025' | 'gemini-2.5-flash-preview-05-20' | 'gemini-2.5-flash-preview-04-17' | 'gemini-2.5-flash-lite-preview-06-17' | 'gemini-2.0-flash-lite-001' | 'gemini-2.0-flash-001' | 'gemini-1.5-flash-002' | 'gemini-1.5-flash-001' | 'gemini-1.5-pro-002' | 'gemini-1.5-pro-001' | 'claude-sonnet-4@20250514' | 'claude-sonnet-4-5@20250929' | 'claude-haiku-4-5@20251001' | 'claude-3-7-sonnet@20250219' | 'claude-3-5-sonnet@20240620' | 'claude-3-5-sonnet-v2@20241022' | 'claude-3-haiku@20240307' | 'gpt-5-2025-08-07' | 'gpt-5.1-2025-11-13' | 'gpt-5.2-2025-12-11' | 'gpt-5.4-2026-03-05' | 'gpt-5.4-mini-2026-03-17' | 'gpt-5.4-nano-2026-03-17' | 'gpt-5.5-2026-04-23' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'gpt-4o-mini-2024-07-18' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4-0613' | 'gpt-4-0314' | 'gpt-4-turbo-2024-04-09' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-1106' | 'watt-tool-8b' | 'watt-tool-70b' - `language` string, nullable: Language of the agent - `tool_ids` string[], nullable: If set, only these tools are available in the conversation, including tools on workflow nodes. Each ID must be attached to the agent. - `native_mcp_server_ids` string[], nullable: If set, the agent uses only these native MCP servers. Each ID must be attached to the agent. - `knowledge_base_ids` string[], nullable: If set, the agent uses only these knowledge base documents. Each ID must be attached to the agent. - `procedure_ids` string[], nullable: If set, only these procedures are available to the starting agent. Each ID must be attached to that agent. An empty list disables all of that agent's procedures. Not applied after an agent transfer. Requires enable_procedure_ids_from_client. - `custom_llm_extra_body` object, nullable: Extra fields for the request body that goes to the custom LLM. - `environment` string, nullable: The environment to use for resolving environment variables (e.g. 'production', 'staging'). Defaults to the branch's environment, then 'production'. - `user_id` string, nullable: ID of the end user participating in this conversation (for agent owner's user identification) - `dynamic_variables` object ## Response `200` Successful Response - CreateAgentConversationResponse - `conversation_id` string, required ## Other responses - `422`: Validation Error ## Changes - **2026-11-12** `f2fab82c4571`: 1 info - endpoint added [Operation history](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/changes/v1/convai/conversations/post.md) --- [API](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation.md) - [All operations](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/revisions/f2fab82c4571?raw)