> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Retrieval

> Test knowledge retrieval with a query to see what the agent would find.

<RequestExample>
  ```bash cURL theme={null}
  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
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.thinnest.ai/knowledge/test-retrieval"
  headers = {
      "Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
      "Content-Type": "application/json",
  }

  payload = {
    "agent_id": "ag_c47e7c97_b2f2",
    "query": "What is your return policy?",
    "top_k": 5
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.thinnest.ai/knowledge/test-retrieval", {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
    "agent_id": "ag_c47e7c97_b2f2",
    "query": "What is your return policy?",
    "top_k": 5
  }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      payload := []byte(`{
    "agent_id": "ag_c47e7c97_b2f2",
    "query": "What is your return policy?",
    "top_k": 5
  }`)
      req, _ := http.NewRequest("POST", "https://api.thinnest.ai/knowledge/test-retrieval", bytes.NewBuffer(payload))
      req.Header.Set("Authorization", "Bearer YOUR_THINNESTAI_API_KEY")
      req.Header.Set("Content-Type", "application/json")

      resp, err := http.DefaultClient.Do(req)
      if err != nil { panic(err) }
      defer resp.Body.Close()
      body, _ := io.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```
</RequestExample>

***

## Request Body

<ParamField body="agent_id" type="string" required>
  The agent's public ID (ag\_\*)
</ParamField>

<ParamField body="query" type="string" required>
  The search query (natural language question)
</ParamField>

<ParamField body="top_k" type="integer" default="5">
  Number of most relevant chunks to return (1–20)
</ParamField>

***

## Response `200`

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="results" type="array">
  Ranked list of matching chunks
</ResponseField>

<ResponseField name="results[].content" type="string">
  The text content of the chunk
</ResponseField>

<ResponseField name="results[].source_name" type="string">
  Name of the knowledge source
</ResponseField>

<ResponseField name="results[].source_type" type="string">
  Source type (text, url, file, etc.)
</ResponseField>

<ResponseField name="results[].similarity_score" type="number">
  Cosine similarity (0.0–1.0). Higher = more relevant
</ResponseField>

<ResponseField name="results[].chunk_index" type="integer">
  Position of this chunk within its source
</ResponseField>

<ResponseField name="query" type="string">
  The original search query
</ResponseField>

<ResponseField name="total_results" type="integer">
  Number of results returned
</ResponseField>

***

## 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 |