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

# Search Documents

> Searches indexed documents using vector similarity search

## Request Body

<ParamField body="query" type="string" required>
  Search query text
</ParamField>

<ParamField body="projectId" type="string" required>
  Project ID to search within
</ParamField>

<ParamField body="topK" type="number" default={5}>
  Maximum number of results to return
</ParamField>

<ParamField body="minScore" type="number" default={0.5}>
  Minimum similarity score threshold (0-1)
</ParamField>

<ParamField body="searchType" type="string">
  Search algorithm type

  * `semantic` - Pure vector similarity search
  * `mrr` - Maximal Marginal Relevance (diverse results)
  * `hybrid` - Combines semantic and keyword search
</ParamField>

<ParamField body="alpha" type="number">
  Balance between semantic and keyword search in hybrid mode (0-1)

  * `0` = Pure keyword search
  * `1` = Pure semantic search
  * `0.5` = Equal weight (default)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the search was successful
</ResponseField>

<ResponseField name="documents" type="array">
  Array of matching document chunks

  <Expandable title="Document Object">
    <ResponseField name="id" type="string">
      Document chunk ID
    </ResponseField>

    <ResponseField name="content" type="string">
      Document content/text
    </ResponseField>

    <ResponseField name="score" type="number">
      Similarity score (0-1)
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Document metadata (fileName, fileType, etc.)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  Status message or error details
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.example.com/api/knowledge/search \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "How do I configure authentication?",
      "projectId": "proj_123",
      "topK": 5,
      "minScore": 0.7,
      "searchType": "semantic"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.example.com/api/knowledge/search', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'How do I configure authentication?',
      projectId: 'proj_123',
      topK: 5,
      minScore: 0.7,
      searchType: 'semantic'
    })
  });

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

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

  response = requests.post(
      'https://api.example.com/api/knowledge/search',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'query': 'How do I configure authentication?',
          'projectId': 'proj_123',
          'topK': 5,
          'minScore': 0.7,
          'searchType': 'semantic'
      }
  )

  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "documents": [
      {
        "id": "chunk_abc123",
        "content": "To configure authentication, navigate to Settings > Security...",
        "score": 0.89,
        "metadata": {
          "fileName": "setup-guide.pdf",
          "fileType": "pdf",
          "pageNumber": 12,
          "chunkIndex": 5
        }
      },
      {
        "id": "chunk_def456",
        "content": "Authentication can be enabled using OAuth 2.0 or API keys...",
        "score": 0.82,
        "metadata": {
          "fileName": "api-reference.md",
          "fileType": "markdown",
          "section": "Authentication"
        }
      }
    ],
    "message": "Found 2 relevant documents"
  }
  ```

  ```json No Results theme={null}
  {
    "success": true,
    "documents": [],
    "message": "No documents found matching the query"
  }
  ```
</ResponseExample>