# ElevenLabs Agents (ConvAI) API — Verified Notes

Verified 2026-11-12 against the live docs at https://elevenlabs.io/docs (machine-readable `.md` pages).
API base: `https://api.elevenlabs.io` (regional bases also documented: `api.us.elevenlabs.io`, `api.eu.residency.elevenlabs.io`, `api.in.residency.elevenlabs.io`, `api.sg.elevenlabs.io`).
Note: the product is now branded "ElevenAgents" in the docs; endpoint paths still use `/v1/convai/...`.

---

## 1. Agents API

Source: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/get
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/update

- `GET /v1/convai/agents/{agent_id}` — returns `agent_id`, `name`, `conversation_config` (ConversationalConfig), `metadata`, `platform_settings`, etc. Optional query params: `version_id`, `branch_id`.
- `PATCH /v1/convai/agents/{agent_id}` — "Patches an Agent settings"; JSON body with the same structure (`name`, `conversation_config`, `platform_settings`, `tags`, ...). Optional `branch_id` query param. (`enable_versioning_if_not_enabled` is deprecated/ignored — all agents are versioned.)

### knowledge_base JSON path (exact)

```
conversation_config.agent.prompt.knowledge_base   // list of KnowledgeBaseLocator
```

Structure: `conversation_config` → `agent` (AgentConfig) → `prompt` (PromptAgentApiModel) → `knowledge_base`.

**KnowledgeBaseLocator** (each entry):

| Field | Type | Notes |
|---|---|---|
| `type` | enum, required | `file`, `url`, `text`, `folder` |
| `name` | string, required | |
| `id` | string, required | knowledge base document id |
| `usage_mode` | enum, optional, default `auto` | `prompt` or `auto` |

Example from the Get agent response example:

```json
"knowledge_base": [
  { "type": "file", "name": "My Knowledge Base", "id": "123", "usage_mode": "auto" }
]
```

Related fields in the same `prompt` object: `tool_ids` (list of tool IDs — tools attachment, see §5), `rag` (RagConfig: `enabled`, `embedding_model` (`e5_mistral_7b_instruct` | `multilingual_e5_large_instruct`), `max_vector_distance` default 0.6, `max_documents_length` default 50000, `max_retrieved_rag_chunks_count` default 20), and a deprecated inline `tools` list ("use tool_ids instead").

---

## 2. Knowledge Base API

Index: https://elevenlabs.io/docs/eleven-agents/api-reference/llms.txt

### Create document from text
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/create-from-text

`POST /v1/convai/knowledge-base/text` — body:

```json
{ "text": "required text content", "name": "optional name", "parent_folder_id": "optional" }
```

Response: `{ "id": "...", "name": "...", "folder_path": [...] }`

Also: `POST /v1/convai/knowledge-base/url` (create-from-url), `POST /v1/convai/knowledge-base/file` (create-from-file, multipart).

### Get document
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-document

`GET /v1/convai/knowledge-base/{documentation_id}` (optional `agent_id` query param). Response is a discriminated union on `type` (`url` | `file` | `text` | `folder`) with `id`, `name`, `metadata`, `extracted_inner_html`, `supported_usages` (list of `prompt`/`auto`), `access_info`, `content_format` (`html` | `markdown`), folder fields.
Full content: `GET /v1/convai/knowledge-base/{documentation_id}/content` (get-content).

### List documents
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/list

`GET /v1/convai/knowledge-base` — query params: `page_size` (default 30, max 100), `cursor`, `search` (name prefix), `types` (`file|url|text|folder`), `created_by_user_id` (`@me` supported), `parent_folder_id`, `ancestor_folder_id`, `folders_first`, `sort_by` (`name|created_at|updated_at|size`), `sort_direction`. Response: `{ documents, has_more, next_cursor }`.

### Update document — CONTENT IS UPDATABLE IN PLACE
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/update
Source: https://elevenlabs.io/docs/eleven-agents/customization/knowledge-base/manage-documents

`PATCH /v1/convai/knowledge-base/{documentation_id}` — "Update the name, content and/or auto-sync settings of a document." Body:

- `name` (optional)
- `content` (optional) — "Updated content for the document. **Only supported for text documents, URL documents with auto-sync disabled, and file documents that are not synced from an external source.**"
- `enable_auto_sync`, `auto_remove`, `minimum_frequency_days`, `tighten_only` (auto-sync/folder settings)

Replace a file document's underlying file: `POST /v1/convai/knowledge-base/{documentation_id}/update-file` (update-file page; multipart `file`).

**RAG re-indexing on content update is automatic.** Manage-documents guide: "Editing a document automatically regenerates its content-search chunks and RAG embeddings, so search and agent retrieval stay in sync." Also: "Refreshing [a URL document] re-indexes the document so RAG-enabled agents use the updated content." (refresh endpoint: `POST /v1/convai/knowledge-base/{documentation_id}/refresh` — see index.)

### RAG index endpoints
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/compute-rag-index
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/knowledge-base/get-rag-index

- `POST /v1/convai/knowledge-base/{documentation_id}/rag-index` — body `{ "model": "e5_mistral_7b_instruct" | "multilingual_e5_large_instruct" }`. Idempotent: triggers indexing if not indexed, otherwise returns current status. Response: `{ id, model, status, progress_percentage, document_model_index_usage: { used_bytes } }`; `status` ∈ `new, created, processing, failed, succeeded, rag_limit_exceeded, document_too_small, cannot_index_folder`.
- `GET /v1/convai/knowledge-base/{documentation_id}/rag-index` — `{ "indexes": [ ...same model... ] }`.
- Also documented: RAG index overview, batch compute, delete RAG index (see API index).

### usage_mode auto vs prompt
Source: https://elevenlabs.io/docs/eleven-agents/customization/knowledge-base/rag

- **auto (default)**: document only retrieved via RAG when relevant to the query.
- **prompt**: document always included in the system prompt regardless of relevance ("Setting too many documents to 'Prompt' mode may exceed context limits").
- Indexing happens automatically when a document is added to an agent with RAG enabled. RAG adds ~250 ms latency. Per-workspace RAG index size limits by tier (Free 1MB → Business 1GB).

---

## 3. Conversations API

### List
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/list

`GET /v1/convai/conversations` — cursor pagination: `cursor`, `page_size` (default 30, max 100), response `{ conversations, has_more, next_cursor }`.
Key filters: `agent_id`, `call_successful` (`success|failure|unknown|error`), `call_start_before_unix` / `call_start_after_unix`, `call_duration_min_secs`/`max_secs`, `user_id`, `evaluation_params` (`criteria_id:result`), `data_collection_params` / `dynamic_variable_params` (`id:op:value`, ops `eq|neq|gt|gte|lt|lte|in`), `tool_names`/`tool_ids` (+ `_successful`/`_errored` variants), `summary_mode` (`include|exclude`), `conversation_initiation_source`, `exclude_statuses` (`initiated|in-progress|processing|done|failed`), `sort_direction` (`asc|desc`, default desc), plus branch/version/topic/tag/termination/guardrail filters.

### Get detail
Source: https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/get

`GET /v1/convai/conversations/{conversation_id}` (optional `format=opentelemetry`). Response top level: `agent_id`, `conversation_id`, `status` (`initiated|in-progress|processing|done|failed`), `transcript` (list), `metadata`, `analysis`, `has_audio`/`has_user_audio`/`has_response_audio`, `conversation_initiation_client_data`, `user_id`, `branch_id`, `version_id`, `tag_ids`, ...

**Transcript turn** (ConversationHistoryTranscriptResponseModel): `role` (`user|agent`), `message` (string, optional), `time_in_call_secs`, `tool_calls` (list: `request_id`, `tool_name`, `params_as_json`, `tool_has_been_called`, `type` ∈ `system|webhook|client|mcp|workflow|api_integration_webhook|smb`, `tool_id`, `tool_details`), `tool_results` (union of result models), `feedback`, `interrupted`, `rag_retrieval_info`, `llm_usage`, `source_medium` (`audio|dtmf|text|image|file`), `original_message`, `created_at_unix_ms`, etc.

**analysis** (ConversationHistoryAnalysisCommonModel):
- `call_successful` (required, `success|failure|unknown`)
- `transcript_summary` (required string), `call_summary_title`, `call_success_score`
- `evaluation_criteria_results` — map keyed by criteria id → `{ criteria_id, result (success|failure|unknown), rationale, scoring_mode (binary|numeric_uniform), score, max_score }` (plus `..._results_list` list form)
- `data_collection_results` — map keyed by data collection id → `{ data_collection_id, rationale, name, value (any), json_schema }` (plus list form)
- `scoped` — per-agent scoped results for multi-agent calls.

**metadata** (ConversationHistoryMetadataCommonModel): `start_time_unix_secs` (required), `call_duration_secs` (required), `cost`, `charging`, `phone_call`, `batch_call`, `termination_reason`, `main_language`, `rag_usage`, `feedback`, `conversation_initiation_source`, `timezone`, `error`, ...

**Dynamic variables**: `conversation_initiation_client_data.dynamic_variables` — map of name → any JSON value; includes `system__*` variables.

**Dashboard deep-link URL for a conversation: UNVERIFIED.** The docs link to the dashboard sections (`https://elevenlabs.io/app/agents`, `.../app/agents/settings`, `.../app/agents/knowledge-base`) but I found no documented per-conversation URL format. There is `GET /v1/convai/conversations/resolve?agent_id=...&reference=...` to resolve an external reference (e.g. a Zendesk ticket URL) to a conversation (https://elevenlabs.io/docs/eleven-agents/api-reference/conversations/resolve), but no documented `app/...` conversation-history link format.

---

## 4. Post-call webhooks

Source: https://elevenlabs.io/docs/eleven-agents/workflows/post-call-webhooks
Source (retries/general webhooks): https://elevenlabs.io/docs/eleven-api/resources/webhooks
Source (signature wire format): https://elevenlabs.io/docs/eleven-agents/customization/integrations/custom_channel

### Configuration
- Workspace-level: enabled for all agents via ElevenAgents settings page (`https://elevenlabs.io/app/agents/settings`). Webhooks themselves are created in general settings (workspace admins only) / via `elevenlabs.webhooks.create` SDK (settings: `auth_type: "hmac"`, `name`, `webhook_url`, optional `request_headers` custom headers — write-only, not returned by list).
- Per-agent override: `platform_settings.workspace_overrides.webhooks` on the agent, e.g.

```json
{ "platform_settings": { "workspace_overrides": { "webhooks": {
    "post_call_webhook_id": "wh_abc123",
    "events": ["transcript", "audio"] } } } }
```

Event types for the `events` array: `transcript`, `audio`, `call_initiation_failure`, `answering_machine_detection`, `unredacted_transcript`, `unredacted_audio`.

### Payload
Three webhook types, all shaped `{ "type": ..., "event_timestamp": <unix secs>, "data": {...} }`:
- `post_call_transcription` — `data` is the ConversationHistoryCommonModel structure (same shape as GET conversation detail: `agent_id`, `agent_name`, `conversation_id`, `status`, `transcript`, `metadata`, `analysis`, `conversation_initiation_client_data` incl. `dynamic_variables`, `has_audio`, ...).
- `post_call_audio` — minimal: `agent_id`, `conversation_id`, `branch_id`, `version_id`, `environment`, `full_audio` (base64 MP3). No transcript/analysis.
- `call_initiation_failure` — `agent_id`, `conversation_id`, `failure_reason` (`busy|no-answer|unknown`), `metadata` (provider-specific, `type: "sip"|"twilio"`).

### HMAC signature
- Header: **`ElevenLabs-Signature`**, format `t=<unix_timestamp>,v0=<hex_digest>`.
- Digest: **HMAC-SHA256 over `{timestamp}.{raw_request_body}`** using the webhook's shared secret (generated at webhook creation).
- Verify the raw body before JSON parsing; reject stale timestamps — the documented example code uses a **30-minute tolerance** (`abs(now - t) > 30*60` → reject). (Exact wire format + sample verification code are documented on the Custom Channel page; the post-call webhook page documents the same `ElevenLabs-Signature` header verified via SDK helpers `elevenlabs.webhooks.constructEvent(payload, signature, secret)` / Python `construct_event(rawBody=..., sig_header=..., secret=...)`, which "verify the signature, validate the timestamp, and parse the JSON payload".)

### Retries / failure handling
- Must return HTTP 200 to count as delivered.
- Retries are opt-in per webhook (disabled by default). Up to 5 attempts: immediate, 30 s, 2 min, 8 min, 30 min (+ up to 10% jitter). Retryable: 5xx, 429, 408, connection errors/timeouts. Other 4xx are NOT retried. Retry payload is identical — handlers should be idempotent (dedupe on `event_timestamp` + `conversation_id`).
- Limits: 100 pending retry jobs per webhook; audio payloads > 50 MiB delivered once without retry; queued audio retries capped at 400 MiB per webhook.
- Auto-disable: 10+ consecutive failures AND (never delivered successfully OR last success > 7 days ago); admins emailed; manual re-enable required.

---

## 5. Server (webhook) tools

Source: https://elevenlabs.io/docs/eleven-agents/api-reference/tools/create (schema identical in get/update)
Source (guide): https://elevenlabs.io/docs/eleven-agents/customization/tools/webhook-tools
Source (dynamic variables): https://elevenlabs.io/docs/eleven-agents/customization/personalization/dynamic-variables

### Tools API (standalone, workspace-level)
- `GET /v1/convai/tools` (list), `GET /v1/convai/tools/{tool_id}`, `POST /v1/convai/tools` (create), `PATCH /v1/convai/tools/{tool_id}` (update), `DELETE /v1/convai/tools/{tool_id}`, `GET /v1/convai/tools/{tool_id}/dependent-agents`. (Index: https://elevenlabs.io/docs/eleven-agents/api-reference/llms.txt)
- **Attachment to agent: by ID** — `conversation_config.agent.prompt.tool_ids` (list of tool IDs). The inline `conversation_config.agent.prompt.tools` list is **deprecated** ("use tool_ids instead").

### Webhook tool config (`tool_config`, `type: "webhook"`)
Required: `name`, `description`, `api_schema` (WebhookToolApiSchemaConfig):

| Field | Notes |
|---|---|
| `url` | required; may contain path placeholders e.g. `https://example.com/agents/{agent_id}` |
| `method` | enum `GET POST PUT PATCH DELETE`, default GET |
| `request_headers` | map header name → string \| ConvAiSecretLocator \| ConvAiDynamicVariable \| ConvAiEnvVarLocator |
| `path_params_schema` | map placeholder → LiteralJsonSchemaProperty |
| `query_params_schema` | `{ properties: map<string, LiteralJsonSchemaProperty>, required: [...] }` |
| `request_body_schema` | ObjectJsonSchemaProperty (JSON body for POST/PUT/PATCH) |
| `response_body_schema` | documentation only; not surfaced to LLM |
| `response_filter` | optional allow-list filter applied to response **before the LLM sees it** ("so large responses don't pollute the context"; defaults to full response) |
| `content_type` | `application/json` (default) or `application/x-www-form-urlencoded` |
| `auth_connection` / `auth_resolved_params` | optional workspace auth connection (OAuth2 client credentials, OAuth2 JWT, Basic, bearer) |

Each parameter property (LiteralJsonSchemaProperty) has `type` plus exactly ONE value source: `description` (LLM provides), `dynamic_variable`, `constant_value`, `is_system_provided`, or `is_omitted`; optional `enum` and `allowed_values` (server-side rejection guard).

Other webhook tool fields: `execution_mode` (`immediate|post_tool_speech|async`), `response_timeout_secs` (**default 20, webhook tools: 5–300 s**; client tools: 1–120 or -1), `tool_error_handling_mode` (`auto|summarized|passthrough|hide`), `assignments` (extract values from tool responses into dynamic variables), `pre_tool_speech`, `interruption_mode`, `follow_redirects` (+ `follow_redirects_allowed_domains`), `response_mocks` (top-level sibling of `tool_config`).

### Secret headers
- `request_headers` value can be a **ConvAiSecretLocator: `{ "secret_id": "..." }`** referencing a workspace secret.
- Workspace secrets API: `GET/POST /v1/convai/secrets`, `GET/PATCH/DELETE /v1/convai/secrets/{secret_id}` (source: https://elevenlabs.io/docs/eleven-agents/api-reference/workspace/secrets/create). Guide: add a header, select type "Secret", "Create New Secret" (bearer tokens etc.); OAuth connections configured under Workspace Auth Connections in agent settings.

### Dynamic variables
- Templated with `{{variable_name}}` in prompts, first messages and tool parameters; a tool parameter can bind via `"dynamic_variable": "<name>"`.
- Built-in system vars (reserved `system__` prefix, auto-populated): `system__agent_id`, `system__current_agent_id`, `system__conversation_id`, `system__caller_id`, `system__called_number`, `system__call_sid`, `system__call_id`, `system__user_id`, `system__initiator_id`, `system__channel`, `system__is_text_only`, `system__environment`, `system__timezone`, `system__time*`, `system__call_duration_secs`, `system__agent_turns`, `system__conversation_history`, `system__uploaded_file_ids`, etc.
- `secret__` prefix = secret dynamic variables (never sent to the LLM; usable in headers/params).
- Custom vars passed at session start: JS/React SDK `Conversation.startSession({ agentId, dynamicVariables: { user_name: "Angelo" } })`; Python `ConversationInitiationData(dynamic_variables=...)`; also `conversation_initiation_client_data.dynamic_variables` in the conversation-start payload / returned in conversation details and webhooks.
- Placeholders for testing: `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders` (map name → value) on the agent.
- Tools can update dynamic variables via `assignments` (DynamicVariableAssignment).

---

## 6. Agent analysis config (evaluation criteria & data collection)

Source: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/get (schemas)
Source: https://elevenlabs.io/docs/eleven-agents/customization/agent-analysis/success-evaluation
Source: https://elevenlabs.io/docs/eleven-agents/customization/agent-analysis/data-collection

Exact JSON paths in the agent object:
- **`platform_settings.evaluation.criteria`** — list of PromptEvaluationCriteria:
  - `id` (required), `name` (required), `conversation_goal_prompt` (required), `type: "prompt"`, `use_knowledge_base` (default false), `scope` (`conversation|agent`), `llm` (per-criterion override), `scoring_mode` (`binary|numeric_uniform`), `max_score` (default 100), `score_instructions`. Limit: 30 criteria per agent.
- **`platform_settings.data_collection`** — map from field ID → AnalysisProperty:
  - `type` (required: `boolean|string|integer|number`), `description` (LLM extracts from this), `name`, `enum`, `dynamic_variable` / `constant_value` / `is_system_provided` / `is_omitted` (mutually exclusive value sources), `allowed_values`, `llm` override.
  - `platform_settings.data_collection_scopes` — map ID → `conversation|agent`.
- Newer: `platform_settings.analysis_items` (AgentAnalysisItemsOutput: `evaluation_criteria` + `data_collection` attached by reference to shared library items) is "the source of truth"; writing `evaluation.criteria`/`data_collection` inline still works and creates/updates the attached items. `platform_settings.analysis_llm` sets the default analysis model.

**Where results appear**: `analysis.evaluation_criteria_results` and `analysis.data_collection_results` (maps keyed by criteria/field id) in both `GET /v1/convai/conversations/{conversation_id}` and the `post_call_transcription` webhook `data.analysis`. Shapes in §3.

---

## 7. Simulate conversation API (smoke test)

Source: https://elevenlabs.io/docs/eleven-agents/api-reference/agents/simulate-conversation

`POST /v1/convai/agents/{agent_id}/simulate-conversation` — **DEPRECATED: "This endpoint will be removed on 31 Oct 2026. Use the `/v1/convai/agent-testing/create` and `/v1/convai/agents/:agent_id/run-tests` endpoints to create and run simulations."** Still live today.

- Request: `simulation_specification` (required; `simulated_user_config` = AgentConfig of the simulated user — e.g. `prompt.prompt` describing the user persona, `first_message`, `language`; optional `tool_mock_config`, `partial_conversation_history`, `dynamic_variables`), `extra_evaluation_criteria` (list of PromptEvaluationCriteria), `new_turns_limit` (default 100).
- Response: `{ "simulated_conversation": [transcript turns, same model as §3], "analysis": {call_successful, transcript_summary, evaluation_criteria_results, ...} }`.
- Streaming variant: `POST /v1/convai/agents/{agent_id}/simulate-conversation/stream` (https://elevenlabs.io/docs/eleven-agents/api-reference/agents/simulate-conversation-stream).
- Guide: https://elevenlabs.io/docs/eleven-agents/guides/simulate-conversation
- Replacement test endpoints (from the deprecation notice + API index "Tests" section): create agent tests (`/v1/convai/agent-testing/create`) and run them (`/v1/convai/agents/{agent_id}/run-tests`).

---

## 8. Auth & rate limits

Source: https://elevenlabs.io/docs/api-reference/authentication

- All requests: **`xi-api-key: <API key>`** header. Keys support scope restriction, credit quota, and IP allowlisting (403 for non-allowlisted IPs). Never expose client-side; single-use tokens exist for client-side connections (https://elevenlabs.io/docs/api-reference/tokens/create).
- **Rate limits for the convai REST endpoints: UNVERIFIED** — no per-endpoint rate-limit numbers are published in the API reference pages fetched. Related documented limits: subscription-tier concurrency limits for running conversations (models/overview + concurrency estimator at https://elevenlabs.io/docs/overview/administration/workspaces/concurrency-estimator), webhook retry on 429, list endpoints capped at `page_size` ≤ 100, RAG storage limits per tier (§2).

---

## Unverified / caveats

- **Conversation dashboard deep-link URL format**: not found in docs — UNVERIFIED.
- **REST rate limits** for `/v1/convai/*`: not documented — UNVERIFIED.
- The post-call-webhook page itself doesn't restate the `t=,v0=` wire format (it points to SDK `constructEvent`); the explicit format + HMAC-SHA256 over `{timestamp}.{raw_body}` + 30-min staleness check is documented on the Custom Channel page for the same `ElevenLabs-Signature` header.
- `simulate-conversation` is deprecated with a removal date (31 Oct 2026) — plan smoke tests around agent-testing endpoints.
