curl -X POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/knowledge-base/rag-query?branch_id=branch-id' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "example-query",
  "use_agent_defaults": true,
  "max_documents_length": 0,
  "max_retrieved_rag_chunks_count": 0
}'

# POST /v1/convai/agents/{agent_id}/knowledge-base/rag-query (ElevenLabs API)
Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20

> Query Agent Knowledge Base Rag

## 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 POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/knowledge-base/rag-query?branch_id=branch-id' \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"example-query","use_agent_defaults":true}'

## Parameters
| Name | In | Type | Required | Description |
| :--- | :--- | :--- | :--- | :--- |
| agent_id | path | string | Yes | The id of an agent. This is returned... |
| query | body | string | Yes | Query to run against the agent's know... |
| branch_id | query | string | No | The ID of the branch to use |
Other params: use_agent_defaults, max_documents_length, max_retrieved_rag_chunks_count

## Response (200 OK)
{"chunks":[{}],"retrieval_query":"How do I reset my password?"}

---
Need an API key? Get one at https://elevenlabs.io/app/sign-up

POST

POST /v1/convai/agents/{agent_id}/knowledge-base/rag-query — ElevenLabs API

ElevenLabs API

Query Agent Knowledge Base Rag

Base URL: https://api.elevenlabs.io
Auth: xi-api-key: <ELEVENLABS_API_KEY>
Last verified: 2026-10-20 · upstream hash matched

Actions Try in browser→

Agents: curl -H "Accept: text/markdown" this URL
→ 232 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 POST 'https://api.elevenlabs.io/v1/convai/agents/agent-id/knowledge-base/rag-query?branch_id=branch-id' \  -H "xi-api-key: $ELEVENLABS_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "query": "example-query",  "use_agent_defaults": true,  "max_documents_length": 0,  "max_retrieved_rag_chunks_count": 0}'

Parameters

Name	In	Type	Required	Description
agent_id	path	string	Yes	The id of an agent. This is returned on agent creation.
branch_id	query	string	No	The ID of the branch to use
query	body	string	Yes	Query to run against the agent's knowledge base RAG index.
use_agent_defaults	body	boolean	No	When true (the default), retrieval uses the agent's own RAG settings, reproducing exactly what the agent would retrieve. Set to false to retrieve with neutral default RAG settings instead (the agent's embedding model is always kept, since it determines which vector index exists). Useful for auditing the knowledge base independently of how a particular agent is tuned.
max_documents_length	body	integer	No	Optional maximum total character length of document chunks returned. Overrides the selected RAG settings for this query only.
max_retrieved_rag_chunks_count	body	integer	No	Optional maximum number of document chunks retrieved. Overrides the selected RAG settings for this query only.

Response 200 OK

{
  "chunks": [
    {
      "chunk_id": "chunk_498cjVigY5qzO86Huf0OWal",
      "content_format": "html",
      "document_id": "doc_J3Pbu5gP6NNKBscdCdwB",
      "document_name": "Account FAQ",
      "document_type": "url",
      "source_url": "https://example.com/account-faq?utm_medium=agents_citation&utm_source=elevenlabs",
      "text": "To reset your password, open Settings and choose Security...",
      "vector_distance": 0.21
    }
  ],
  "retrieval_query": "How do I reset my password?"
}

Get a free ElevenLabs API key → sponsored

Affiliate link - we may earn a commission, at no extra cost to you.