Test Retrieval
Test knowledge retrieval with a query to see what the agent would find.
POST
/knowledge/test-retrievalRun a similarity search against an agent's knowledge base. Returns the most relevant chunks.
No parameters for this endpoint.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | string | Yes | — | The agent's public ID (ag_*) |
query | string | Yes | — | The search query (natural language question) |
top_k | integer | No | 5 | Number of most relevant chunks to return (1–20) |
Response 200
{
"results": [
{
"content": "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging.",
"source_name": "Return Policy",
"source_type": "text",
"similarity_score": 0.94,
"chunk_index": 0
},
{
"content": "Refunds are processed within 5-7 business days after we receive the returned item.",
"source_name": "Return Policy",
"source_type": "text",
"similarity_score": 0.87,
"chunk_index": 1
},
{
"content": "Exchanges can be made for items of equal or lesser value. Price differences are refunded to the original payment method.",
"source_name": "FAQ Document",
"source_type": "text",
"similarity_score": 0.72,
"chunk_index": 3
}
],
"query": "What is your return policy?",
"total_results": 3
}Response Fields
| Field | Type | Description |
|---|---|---|
results | array | Ranked list of matching chunks |
results[].content | string | The text content of the chunk |
results[].source_name | string | Name of the knowledge source |
results[].source_type | string | Source type (text, url, file, etc.) |
results[].similarity_score | float | Cosine similarity (0.0–1.0). Higher = more relevant |
results[].chunk_index | integer | Position of this chunk within its source |
query | string | The original search query |
total_results | integer | Number of results returned |
Use Cases
- Debug retrieval quality: Verify that the right content is being found for specific questions
- Tune chunk size: Check if chunks are too large (low relevance) or too small (missing context)
- Validate knowledge: Confirm that newly added sources are indexed and retrievable
Errors
| Code | Description |
|---|---|
401 | Missing or invalid authentication |
404 | Agent not found or no knowledge sources attached |