PATCH
/v1/convai/agents/{agent_id}
ElevenLabs APIPatches An Agent Settings
- 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
→ 216 tokens · Vary: Accept
→ 216 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 PATCH 'https://api.elevenlabs.io/v1/convai/agents/agent-id?enable_versioning_if_not_enabled=true&branch_id=branch-id' \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "conversation_config": {}, "platform_settings": {}, "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" ], "version_description": "string", "procedures": {}}'Get a free ElevenLabs API key → sponsored
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | path | string | Yes | The id of an agent. This is returned on agent creation. |
| enable_versioning_if_not_enabled | query | boolean | No | Deprecated: all agents are versioned. This parameter is ignored. |
| branch_id | query | string | No | The ID of the branch to use |
| conversation_config | body | object | No | Conversation configuration for an agent |
| 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 |
| version_description | body | string | No | Description for this version when publishing changes (only applicable for versioned agents) |
| procedures | body | object | No | Procedure versions to publish, keyed by procedure_id. When provided, this map replaces the procedures from the current draft or branch tip. When omitted or null, unpublished procedure edits are used if present; otherwise, the branch tip's procedures are retained. Pass an empty object to remove all procedures. |
Response 200 OK
{
"agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
"name": "My Agent",
"workflow": {
"edges": {
"entry_to_tool_a": {
"forward_condition": {
"condition": "Tool A condition",
"type": "llm"
},
"source": "entry_node",
"target": "tool_node_a"
},
"start_to_entry": {
"forward_condition": {
"type": "unconditional"
},
"source": "start_node",
"target": "entry_node"
},
"tool_a_to_failure": {
"forward_condition": {
"successful": false,
"type": "result"
},
"source": "tool_node_a",
"target": "failure_node"
},
"tool_a_to_tool_b": {
"forward_condition": {
"successful": true,
"type": "result"
},
"source": "tool_node_a",
"target": "tool_node_b"
},
"tool_b_to_agent_transfer": {
"forward_condition": {
"type": "unconditional"
},
"source": "tool_node_b",
"target": "success_transfer"
},
"tool_b_to_conversation": {
"forward_condition": {
"condition": "Conversation condition",
"type": "llm"
},
"source": "tool_node_b",
"target": "success_conversation"
},
"tool_b_to_end": {
"forward_condition": {
"condition": "End condition",
"type": "llm"
},
"source": "tool_node_b",
"target": "success_end"
},
"tool_b_to_phone": {
"forward_condition": {
"expression": {
"children": [
{
"name": "force_phone_transfer",
"type": "dynamic_variable"
},
{
"prompt": "Phone condition",
"type": "llm",
"value_schema": {
"description": "Phone condition",
"type": "boolean"
}
},
{
"left": {
"name": "mode",
"type": "dynamic_variable"
},
"right": {
"type": "string_literal",
"value": "dev"
},
"type": "eq_operator"
}
],
"type": "or_operator"
},
"type": "expression"
},
"source": "tool_node_b",
"target": "success_phone"
}
},
"nodes": {
"entry_node": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"conversation_config": {},
"edge_order": [
"entry_to_tool_a"
],
"entry_behavior": "auto",
"label": "Entry",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"failure_node": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"conversation_config": {},
"edge_order": [],
"entry_behavior": "auto",
"label": "Failure",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"start_node": {
"edge_order": [
"start_to_entry"
],
"position": {
"x": 0,
"y": 0
},
"type": "start"
},
"success_conversation": {
"additional_knowledge_base": [],
"additional_prompt": "",
"additional_tool_ids": [],
"conversation_config": {},
"edge_order": [],
"entry_behavior": "auto",
"label": "Success A",
"position": {
"x": 0,
"y": 0
},
"type": "override_agent"
},
"success_end": {
"edge_order": [],
"position": {
"x": 0,
"y": 0
},
"return_when_nested": true,
"type": "end"
},
"success_phone": {
"custom_sip_headers": [],
"edge_order": [],
"position": {
"x": 0,
"y": 0
},
"require_acceptance": false,
"sip_refer_play_dialtone": true,
"transfer_destination": {
"phone_number": "+1234567890",
"type": "phone"
},
"transfer_type": "conference",
"type": "phone_number"
},
"success_transfer": {
"agent_id": "success_transfer_agent",
"delay_ms": 0,
"drop_history": false,
"edge_order": [],
"enable_transferred_agent_first_message": false,
"isolate_history": false,
"position": {
"x": 0,
"y": 0
},
"preserve_client_tts_overrides": false,
"type": "standalone_agent"
},
"tool_node_a": {
"edge_order": [
"tool_a_to_failure",
"tool_a_to_tool_b"
],
"position": {
"x": 0,
"y": 0
},
"tools": [
{
"tool_id": "tool_a"
},
{
"tool_id": "tool_b"
}
],
"type": "tool"
},
"tool_node_b": {
"edge_order": [
"tool_b_to_conversation",
"tool_b_to_end",
"tool_b_to_phone",
"tool_b_to_agent_transfer"
],
"position": {
"x": 0,
"y": 0
},
"tools": [
{
"tool_id": "tool_a"
}
],
"type": "tool"
}
},
"prevent_subagent_loops": false,
"subgraphs": {}
}
}