ElevenLabs MCP Server

# ElevenLabs Tools & Knowledge Base 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 ``` --- ## Tools Management API ### Overview Tools enable Conversational AI agents to perform actions beyond generating text responses. They allow agents to interact with external systems, execute custom logic, or access specific functionalities during conversations. ### Tool Types 1. **Client Tools**: Executed directly on the client-side application (browser, mobile app) 2. **Server Tools**: Custom tools executed on your server-side infrastructure via API calls 3. **System Tools**: Built-in tools (end_call, language_detection, etc.) --- ## Tools API Endpoints ### 1. Create Tool **POST** `/tools` Creates a new tool in the workspace. #### Headers - `xi-api-key` (required): Your ElevenLabs API key - `Content-Type: application/json` #### Request Body ```json { "tool_config": { "type": "webhook", // or "client" "name": "weather_lookup", "description": "Get current weather information for any location", "url": "https://api.weather.com/v1/current", "method": "GET", "headers": { "Authorization": "Bearer YOUR_WEATHER_API_KEY" }, "parameters": [ { "name": "location", "type": "string", "description": "City name or coordinates for weather lookup", "required": true } ] } } ``` #### Server Tool Configuration ```json { "tool_config": { "type": "webhook", "name": "get_customer_data", "description": "Retrieve customer information from database", "url": "https://yourdomain.com/api/customers/{customer_id}", "method": "GET", "headers": { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, "parameters": [ { "name": "customer_id", "type": "string", "description": "Unique customer identifier", "required": true } ] } } ``` #### Client Tool Configuration ```json { "tool_config": { "type": "client", "name": "show_notification", "description": "Display a notification to the user", "parameters": [ { "name": "message", "type": "string", "description": "Notification message to display", "required": true }, { "name": "type", "type": "string", "description": "Notification type: info, warning, error", "required": false } ], "wait_for_response": false } } ``` #### Response ```json { "id": "tool_abc123xyz", "tool_config": { "type": "webhook", "name": "weather_lookup", "description": "Get current weather information for any location", // ... complete tool configuration }, "access_info": { "owner": "workspace_owner_id", "shared": false } } ``` ### 2. Get Tool **GET** `/tools/{tool_id}` Retrieves a specific tool configuration. #### Path Parameters - `tool_id` (required): ID of the tool #### Response ```json { "id": "tool_abc123xyz", "tool_config": { "type": "webhook", "name": "weather_lookup", "description": "Get current weather information", "url": "https://api.weather.com/v1/current", "method": "GET", "parameters": [...] }, "access_info": { "owner": "workspace_owner_id", "shared": false } } ``` ### 3. List Tools **GET** `/tools` Returns all available tools in the workspace. #### Query Parameters - `type` (optional): Filter by tool type (webhook, client) - `limit` (optional): Maximum number of tools to return #### Response ```json { "tools": [ { "id": "tool_abc123xyz", "tool_config": { "type": "webhook", "name": "weather_lookup", "description": "Get current weather information" }, "access_info": { "owner": "workspace_owner_id", "shared": false } } ] } ``` ### 4. Update Tool **PATCH** `/tools/{tool_id}` Updates an existing tool configuration. #### Path Parameters - `tool_id` (required): ID of the tool to update #### Request Body ```json { "tool_config": { "description": "Updated weather lookup with extended forecast", "parameters": [ { "name": "location", "type": "string", "description": "City name, coordinates, or zip code", "required": true }, { "name": "forecast_days", "type": "integer", "description": "Number of forecast days (1-7)", "required": false } ] } } ``` ### 5. Delete Tool **DELETE** `/tools/{tool_id}` Deletes a tool from the workspace. #### Path Parameters - `tool_id` (required): ID of the tool to delete #### Response ```json { "success": true, "message": "Tool deleted successfully" } ``` --- ## Knowledge Base Management API ### Overview Knowledge bases enhance your conversational agents with custom knowledge from documents, URLs, and text content. They support RAG (Retrieval-Augmented Generation) for accessing large knowledge bases efficiently. ### Supported Formats - **Files**: PDF, TXT, DOCX, HTML, EPUB - **URLs**: Documentation pages, product pages (single page scraping) - **Text**: Direct text input ### Limits - **Non-enterprise**: 20MB or 300k characters maximum - **With RAG enabled**: Up to 10MB per knowledge base item --- ## Knowledge Base API Endpoints ### 1. Create Knowledge Base Document from File **POST** `/knowledge-base` Uploads a file to create a knowledge base document. #### Headers - `xi-api-key` (required): Your ElevenLabs API key - `Content-Type: multipart/form-data` #### Request Body (Multipart Form) ``` file: [binary file data] name: "Product Documentation" description: "Complete product specifications and user guide" ``` #### Response ```json { "id": "doc_abc123xyz", "name": "Product Documentation", "description": "Complete product specifications and user guide", "type": "file", "size": 2048576, "status": "processing", "created_at": "2025-01-15T10:30:00Z" } ``` ### 2. Create Knowledge Base Document from URL **POST** `/knowledge-base/create-from-url` Creates a knowledge base document by scraping a webpage. #### Headers - `xi-api-key` (required): Your ElevenLabs API key - `Content-Type: application/json` #### Request Body ```json { "url": "https://docs.example.com/api-reference", "name": "API Reference Documentation", "description": "Complete API documentation and examples" } ``` #### Response ```json { "id": "doc_url123xyz", "name": "API Reference Documentation", "url": "https://docs.example.com/api-reference", "type": "url", "status": "processing", "created_at": "2025-01-15T10:30:00Z" } ``` ### 3. Create Knowledge Base Document from Text **POST** `/knowledge-base/create-from-text` Creates a knowledge base document from direct text input. #### Request Body ```json { "text": "This is the content of the knowledge base document...", "name": "Company Policies", "description": "HR policies and employee handbook" } ``` ### 4. Get Knowledge Base Document **GET** `/knowledge-base/{document_id}` Retrieves details about a specific knowledge base document. #### Path Parameters - `document_id` (required): ID of the knowledge base document #### Response ```json { "id": "doc_abc123xyz", "name": "Product Documentation", "description": "Complete product specifications and user guide", "type": "file", "size": 2048576, "status": "ready", "content_preview": "This document contains comprehensive information about...", "agents": ["agent_123", "agent_456"], "created_at": "2025-01-15T10:30:00Z", "updated_at": "2025-01-15T10:35:00Z" } ``` ### 5. List Knowledge Base Documents **GET** `/knowledge-base` Returns all knowledge base documents in the workspace. #### Query Parameters - `name_filter` (optional): Filter documents by name prefix - `show_only_owned_documents` (optional): If true, returns only owned documents - `document_types` (optional): Filter by document types (file, url, text) - `limit` (optional): Maximum number of documents to return #### Response ```json { "documents": [ { "id": "doc_abc123xyz", "name": "Product Documentation", "type": "file", "size": 2048576, "status": "ready", "created_at": "2025-01-15T10:30:00Z" }, { "id": "doc_url123xyz", "name": "API Reference", "type": "url", "status": "ready", "created_at": "2025-01-15T09:15:00Z" } ] } ``` ### 6. Update Knowledge Base Document **PATCH** `/knowledge-base/{document_id}` Updates an existing knowledge base document. #### Request Body ```json { "name": "Updated Product Documentation", "description": "Updated comprehensive product guide with new features" } ``` ### 7. Delete Knowledge Base Document **DELETE** `/knowledge-base/{document_id}` Deletes a knowledge base document. #### Path Parameters - `document_id` (required): ID of the document to delete #### Response ```json { "success": true, "message": "Knowledge base document deleted successfully" } ``` ### 8. Compute RAG Index **POST** `/knowledge-base/{document_id}/compute-rag-index` Computes the RAG index for a knowledge base document to enable efficient retrieval. #### Path Parameters - `document_id` (required): ID of the document #### Response ```json { "status": "processing", "message": "RAG index computation started" } ``` ### 9. Get Document Content **GET** `/knowledge-base/{document_id}/content` Retrieves the full content of a knowledge base document. #### Response ```json { "id": "doc_abc123xyz", "content": "Full document content...", "chunks": [ { "id": "chunk_1", "content": "First section of the document...", "metadata": { "page": 1, "section": "Introduction" } } ] } ``` ### 10. Get Document Chunk **GET** `/knowledge-base/{document_id}/chunks/{chunk_id}` Retrieves a specific chunk from a knowledge base document. --- ## Agent Integration ### Adding Tools to Agents #### New Format (Recommended) ```json { "conversation_config": { "agent": { "prompt": { "tool_ids": ["tool_abc123xyz", "tool_def456xyz"], "built_in_tools": ["language_detection", "end_call"] } } } } ``` #### Legacy Format (Deprecated - Removed July 23, 2025) ```json { "conversation_config": { "agent": { "prompt": { "tools": [ { "type": "webhook", "name": "weather_lookup", // ... tool configuration } ] } } } } ``` ### Adding Knowledge Base to Agents #### Basic Knowledge Base Assignment ```json { "conversation_config": { "agent": { "knowledge_base": { "document_ids": ["doc_abc123xyz", "doc_def456xyz"] } } } } ``` #### RAG-Enabled Knowledge Base ```json { "conversation_config": { "agent": { "knowledge_base": { "document_ids": ["doc_abc123xyz"], "use_rag": true, "rag_config": { "chunk_size": 1000, "overlap": 200, "top_k": 5 } } } } } ``` --- ## Best Practices ### Tools 1. **Clear Naming**: Use descriptive tool names and parameter descriptions 2. **Error Handling**: Implement proper error handling in server tools 3. **Security**: Store API keys as secrets, use HTTPS for webhooks 4. **Testing**: Test tools thoroughly before deploying to agents 5. **Documentation**: Provide clear descriptions for LLM understanding ### Knowledge Base 1. **Document Quality**: Use well-structured, clear documents 2. **Regular Updates**: Keep knowledge base current and accurate 3. **Size Management**: Monitor document sizes and optimize for RAG 4. **Chunking Strategy**: Use appropriate chunk sizes for RAG 5. **Relevance**: Review conversation transcripts to identify knowledge gaps ### RAG Configuration - **Chunk Size**: 500-1500 characters optimal for most use cases - **Overlap**: 10-20% overlap between chunks - **Top-K**: 3-7 retrieved chunks per query - **Latency**: RAG adds ~500ms to response time --- ## Error Handling ### Common Error Responses ```json { "error": { "type": "validation_error", "message": "Tool name must be unique within workspace", "field": "tool_config.name" } } ``` ### HTTP Status Codes - `200`: Success - `400`: Bad Request - Invalid parameters - `401`: Unauthorized - Invalid API key - `404`: Not Found - Tool/Document doesn't exist - `422`: Unprocessable Entity - Validation error - `429`: Too Many Requests - Rate limit exceeded --- ## Migration Timeline ### Tools Deprecation (Critical) - **July 14, 2025**: Last day for backwards compatibility with `prompt.tools` - **July 15, 2025**: GET endpoints stop returning `tools` field - **July 23, 2025**: Legacy `prompt.tools` permanently removed ### Action Required 1. Migrate from `prompt.tools` to `prompt.tool_ids` 2. Create standalone tools using `/tools` endpoints 3. Update agent configurations to reference tool IDs 4. Use `prompt.built_in_tools` for system tools --- ## Code Examples ### Python Example - Create Tool ```python import requests url = "https://api.elevenlabs.io/v1/convai/tools" headers = { "xi-api-key": "YOUR_API_KEY", "Content-Type": "application/json" } payload = { "tool_config": { "type": "webhook", "name": "weather_lookup", "description": "Get current weather for any location", "url": "https://api.openweathermap.org/data/2.5/weather", "method": "GET", "parameters": [ { "name": "q", "type": "string", "description": "City name for weather lookup", "required": True }, { "name": "appid", "type": "string", "description": "API key for weather service", "required": True } ] } } response = requests.post(url, headers=headers, json=payload) tool_data = response.json() print(f"Created tool with ID: {tool_data['id']}") ``` ### JavaScript Example - Create Knowledge Base from URL ```javascript const url = "https://api.elevenlabs.io/v1/convai/knowledge-base/create-from-url"; const response = await fetch(url, { method: "POST", headers: { 'xi-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: "https://docs.mycompany.com/api", name: "Company API Documentation", description: "Complete API reference for developers" }) }); const document = await response.json(); console.log('Created knowledge base document:', document.id); ``` ### cURL Example - Add Tool to 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 '{ "conversation_config": { "agent": { "prompt": { "tool_ids": ["tool_weather123", "tool_calendar456"], "built_in_tools": ["language_detection", "end_call"] }, "knowledge_base": { "document_ids": ["doc_policies123", "doc_faq456"], "use_rag": true } } } }' ``` --- *Last updated: January 2025* *API Version: v1* *Tools Migration Deadline: July 23, 2025*