# ElevenLabs Conversational AI Agents Management API Documentation
## Base URL
```
https://api.elevenlabs.io/v1/convai
```
## Authentication
All API requests require authentication using the `xi-api-key` header.
```http
xi-api-key: YOUR_API_KEY_HERE
```
---
## Endpoints
### 1. Create Agent
**POST** `/agents/create`
Creates a new conversational AI agent from a configuration object.
#### Headers
- `xi-api-key` (required): Your ElevenLabs API key
- `Content-Type: application/json`
#### Request Body
```json
{
"conversation_config": {
"agent": {
"language": "en",
"prompt": {
"prompt": "You are a helpful assistant...",
"tool_ids": ["tool_id_1", "tool_id_2"],
"built_in_tools": ["language_detection", "end_call"]
},
"first_message": "Hello! How can I help you today?"
},
"asr": {
"quality": "high",
"provider": "elevenlabs",
"user_input_audio_format": "pcm_16000",
"keywords": ["custom", "keywords"]
},
"turn": {
"turn_timeout": 7,
"mode": "turn"
},
"tts": {
"model_id": "eleven_turbo_v2",
"voice_id": "21m00Tcm4TlvDq8ikWAM"
},
"language_presets": [],
"conversation": {}
},
"platform_settings": {
"widget": {},
"privacy": {},
"evaluation_config": {
"criteria": [],
"success_threshold": 0.7
}
},
"name": "My Customer Service Agent"
}
```
#### Response
```json
{
"agent_id": "agent_abc123xyz"
}
```
#### Response Codes
- `200`: Agent created successfully
- `400`: Invalid request body
- `401`: Unauthorized (invalid API key)
---
### 2. Get Agent
**GET** `/agents/{agent_id}`
Retrieves the configuration for a specific agent.
#### Path Parameters
- `agent_id` (required): The ID of the agent
#### Headers
- `xi-api-key` (optional): Your ElevenLabs API key
#### Response
```json
{
"agent_id": "agent_abc123xyz",
"name": "My Customer Service Agent",
"conversation_config": {
"agent": {
"language": "en",
"prompt": {
"prompt": "You are a helpful assistant...",
"tool_ids": ["tool_id_1"],
"built_in_tools": ["language_detection"]
},
"first_message": "Hello! How can I help you today?"
},
"asr": {
"quality": "high",
"provider": "elevenlabs",
"user_input_audio_format": "pcm_16000",
"keywords": []
},
"turn": {
"turn_timeout": 7,
"mode": "turn"
},
"tts": {
"model_id": "eleven_turbo_v2",
"voice_id": "21m00Tcm4TlvDq8ikWAM"
},
"language_presets": [],
"conversation": {}
},
"metadata": {
"created_at": "2025-01-15T10:30:00Z"
},
"platform_settings": {
"widget": {},
"privacy": {},
"evaluation_config": {}
},
"phone_numbers": [],
"access_info": {}
}
```
#### Response Codes
- `200`: Agent retrieved successfully
- `404`: Agent not found
- `401`: Unauthorized
---
### 3. List Agents
**GET** `/agents`
Returns a list of your agents and their metadata with pagination support.
#### Query Parameters
- `cursor` (optional): Pagination cursor for next page
- `page_size` (optional): Maximum number of agents to return (max: 100, default: 30)
#### Headers
- `xi-api-key` (optional): Your ElevenLabs API key
#### Response
```json
{
"agents": [
{
"agent_id": "agent_abc123xyz",
"name": "Customer Service Agent",
"conversation_config": { /* ... */ },
"metadata": {
"created_at": "2025-01-15T10:30:00Z"
}
}
],
"next_cursor": "next_page_token",
"has_more": true
}
```
#### Response Codes
- `200`: Agents listed successfully
- `401`: Unauthorized
---
### 4. Update Agent
**PATCH** `/agents/{agent_id}`
Updates an existing agent's configuration.
#### Path Parameters
- `agent_id` (required): The ID of the agent to update
#### Headers
- `xi-api-key` (optional): Your ElevenLabs API key
- `Content-Type: application/json`
#### Request Body (all fields optional)
```json
{
"conversation_config": {
"agent": {
"prompt": {
"prompt": "Updated prompt text..."
}
},
"tts": {
"voice_id": "new_voice_id"
}
},
"platform_settings": {
"evaluation_config": {
"success_threshold": 0.8
}
},
"name": "Updated Agent Name",
"tags": ["customer-service", "v2"]
}
```
#### Response
```json
{
"agent_id": "agent_abc123xyz",
"name": "Updated Agent Name",
"conversation_config": { /* updated config */ },
"metadata": {
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T14:20:00Z"
},
"platform_settings": { /* updated settings */ }
}
```
#### Response Codes
- `200`: Agent updated successfully
- `400`: Invalid request body
- `404`: Agent not found
- `401`: Unauthorized
---
### 5. Delete Agent
**DELETE** `/agents/{agent_id}`
Permanently deletes an agent.
#### Path Parameters
- `agent_id` (required): The ID of the agent to delete
#### Headers
- `xi-api-key` (required): Your ElevenLabs API key
#### Response
```json
{
"success": true,
"message": "Agent deleted successfully"
}
```
#### Response Codes
- `200`: Agent deleted successfully
- `404`: Agent not found
- `401`: Unauthorized
---
## Configuration Reference
### ASR (Automatic Speech Recognition) Configuration
```json
{
"quality": "high",
"provider": "elevenlabs",
"user_input_audio_format": "pcm_16000",
"keywords": ["optional", "keywords", "array"]
}
```
#### ASR Audio Formats
- `pcm_16000`: 16kHz PCM (default)
- `pcm_22050`: 22.05kHz PCM
- `pcm_24000`: 24kHz PCM
- `pcm_44100`: 44.1kHz PCM
- `ulaw_8000`: 8kHz μ-law
### Turn Management Configuration
```json
{
"turn_timeout": 7,
"mode": "turn"
}
```
#### Turn Modes
- `turn`: Standard turn-taking (default)
- `silence`: Silence-based detection
### TTS (Text-to-Speech) Configuration
```json
{
"model_id": "eleven_turbo_v2",
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"stability": 0.5,
"similarity_boost": 0.8
}
```
#### Available TTS Models
- `eleven_turbo_v2`: High-quality, low-latency (default)
- `eleven_turbo_v2_5`: Enhanced version with better quality
- `eleven_flash_v2_5`: Ultra-low latency (~75ms), 32 languages
- `eleven_multilingual_v2`: Best quality, 29 languages
- `eleven_v3`: Most advanced, 70+ languages (not for real-time)
### System Tools
```json
{
"built_in_tools": [
"language_detection",
"end_call",
"agent_transfer",
"human_transfer",
"wait_for_user"
]
}
```
#### System Tool Descriptions
- `language_detection`: Automatically switches language based on user input
- `end_call`: Terminates conversation when appropriate
- `agent_transfer`: Transfers to specialized agents
- `human_transfer`: Hands off to human operators
- `wait_for_user`: Pauses until user speaks
### Language Support
```json
{
"language": "en",
"language_presets": [
{
"language": "es",
"voice_id": "spanish_voice_id"
},
{
"language": "fr",
"voice_id": "french_voice_id"
}
]
}
```
#### Supported Languages (Flash v2.5 - 32 languages)
English, Spanish, French, German, Italian, Portuguese, Dutch, Polish, Czech, Ukrainian, Russian, Turkish, Swedish, Norwegian, Danish, Finnish, Hungarian, Romanian, Bulgarian, Croatian, Slovak, Slovenian, Estonian, Latvian, Lithuanian, Maltese, Irish, Welsh, Arabic, Hebrew, Hindi, Tamil, Vietnamese
---
## Code Examples
### Python Example - Create Agent
```python
import requests
url = "https://api.elevenlabs.io/v1/convai/agents/create"
headers = {
"xi-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"conversation_config": {
"agent": {
"language": "en",
"prompt": {
"prompt": "You are a helpful customer service agent. Be polite and professional.",
"built_in_tools": ["language_detection", "end_call"]
},
"first_message": "Hello! Welcome to our customer service. How can I assist you today?"
},
"asr": {
"quality": "high",
"user_input_audio_format": "pcm_16000"
},
"turn": {
"turn_timeout": 7,
"mode": "turn"
},
"tts": {
"model_id": "eleven_turbo_v2_5",
"voice_id": "21m00Tcm4TlvDq8ikWAM"
}
},
"name": "Customer Service Agent v1"
}
response = requests.post(url, headers=headers, json=payload)
agent_data = response.json()
print(f"Created agent with ID: {agent_data['agent_id']}")
```
### JavaScript Example - Get Agent
```javascript
const agentId = "agent_abc123xyz";
const url = `https://api.elevenlabs.io/v1/convai/agents/${agentId}`;
const response = await fetch(url, {
headers: {
'xi-api-key': 'YOUR_API_KEY'
}
});
const agent = await response.json();
console.log('Agent configuration:', agent);
```
### cURL Example - Update Agent
```bash
curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_abc123xyz" \
-H "xi-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Customer Service Agent",
"conversation_config": {
"agent": {
"prompt": {
"prompt": "You are an expert customer service representative with 10 years of experience."
}
}
}
}'
```
---
## Error Handling
### Common Error Responses
```json
{
"error": {
"type": "invalid_request_error",
"message": "Invalid conversation_config: missing required field 'agent'",
"param": "conversation_config.agent"
}
}
```
### HTTP Status Codes
- `200`: Success
- `400`: Bad Request - Invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `404`: Not Found - Agent doesn't exist
- `429`: Too Many Requests - Rate limit exceeded
- `500`: Internal Server Error
---
## Rate Limits
- Standard API calls: 100 requests per minute
- Agent creation: 10 requests per minute
- Concurrent conversations depend on your subscription plan
---
## WebSocket Integration
After creating an agent, you can establish real-time conversations using:
```
wss://api.elevenlabs.io/v1/convai/conversation?agent_id={agent_id}
```
For private agents, use the signed URL endpoint:
```
GET /v1/convai/conversation/get_signed_url?agent_id={agent_id}
```
---
## Migration Notes
### Tools Deprecation Timeline
- **Legacy `prompt.tools` array**: Deprecated, use `prompt.tool_ids`
- **July 14, 2025**: Last day for backwards compatibility
- **July 15, 2025**: GET endpoints stop returning `tools` field
- **July 23, 2025**: Legacy `prompt.tools` permanently removed
### Best Practices
1. Always handle API errors gracefully
2. Store agent_id securely for future operations
3. Use appropriate TTS models for your use case
4. Test with different languages and voices
5. Implement proper error handling for WebSocket connections
6. Monitor conversation analytics for optimization
---
*Last updated: January 2025*
*API Version: v1*
