Agents Platform

Query Agent Knowledge Base Rag

Run the agent's exact RAG retrieval for an ad-hoc query and return the ranked chunks the agent would retrieve. Read-only: no conversation is created. The response reflects current retrieval internals and may evolve.

post/v1/convai/agents/{agent_id}/knowledge-base/rag-query

Path parameters

agent_idstring required

The id of an agent. This is returned on agent creation.

Example:agent_3701k3ttaq12ewp8b7qv5rfyszkz

The id of an agent. This is returned on agent creation.

Query parameters

branch_idstring nullable

The ID of the branch to use

Example:agtbranch_0901k4aafjxxfxt93gd841r7tv5t

The ID of the branch to use

Headers

xi-api-keystring nullable

Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

Request body

querystring required

Query to run against the agent's knowledge base RAG index.

use_agent_defaultsboolean

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.

Example request

{
  "query": "How do I reset my password?"
}

Response

Successful Response

retrieval_querystring required

Raw query used for retrieval (echoes the request query).

Example response

{
  "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?"
}

Changes

Changed in 4 of the 32 revisions of this API.5

Sep 4, 2026d393c67c384a1See the full diff
- ○
  added the required property // to the response with the status
  response-required-property-added
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 8, 2026e77a0a530a822See the full diff
- ○
  added the required property // to the response with the status
  response-required-property-added
- ○
  added the required property // to the response with the status
  response-required-property-added
Jul 31, 202672c54eba117e1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 26, 2026494d96419d151See the full diff
- ○
  endpoint added
  endpoint-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history