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

# Semantic Search

> Search vectorized document chunks using natural language queries.

Results are ranked by cosine similarity score. When `node_ids` is provided, the
search uses an optimized database function for better performance.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.chatgrid.ai/v1/boards/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/search" \
    -H "Authorization: Bearer cgk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What were the Q1 revenue numbers?",
      "limit": 5,
      "threshold": 0.6,
      "node_ids": ["e5f6a7b8-c9d0-1234-efab-345678901234"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "dd112233-4455-6677-8899-aabbccddeeff",
        "content": "The quarterly revenue report shows a 15% increase in SaaS subscriptions.",
        "node_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
        "metadata": {
          "source": "annual-report-2026.pdf",
          "page": 3,
          "chunkIndex": 0,
          "totalChunks": 3,
          "sourceType": "api_vectorize"
        },
        "score": 0.87
      },
      {
        "id": "ee223344-5566-7788-99aa-bbccddeeff11",
        "content": "New enterprise deals accounted for $2.3M in recurring revenue.",
        "node_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
        "metadata": {
          "source": "annual-report-2026.pdf",
          "page": 3,
          "chunkIndex": 2,
          "totalChunks": 3,
          "sourceType": "api_vectorize"
        },
        "score": 0.79
      }
    ],
    "has_more": false,
    "cursor": null
  }
  ```
</ResponseExample>