curl -X POST https://api.thinnest.ai/knowledge/test-retrieval \
-H "Authorization: Bearer $THINNESTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "ag_c47e7c97_b2f2",
"query": "What is your return policy?",
"top_k": 5
}'
Request Body
The agent’s public ID (ag_*)
The search query (natural language question)
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
Ranked list of matching chunks
The text content of the chunk
Name of the knowledge source
Source type (text, url, file, etc.)
results[].similarity_score
Cosine similarity (0.0–1.0). Higher = more relevant
Position of this chunk within its source
The original search query
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 |