---
title: "Search with LLM-guided tree traversal"
method: POST
path: "/v1/search"
tags: ["search"]
---

# Search with LLM-guided tree traversal

`POST /v1/search`

Performs an intelligent search across documents using an LLM to navigate the hierarchical tree structure. The LLM evaluates each node's summary to decide which branches to explore, mimicking human reasoning. Returns relevant content with extracted answers and confidence scores.

## Request body

- SearchRequest
  - `query` string, required — The natural language query to search for
  - `document_id` string — Optional document ID to search within (searches all if not provided)
  - `table_id` string — Optional table ID to restrict search to
  - `tags` string[] — Filter by document tags (any match)
  - `metadata` object — Filter by document metadata (author, contract_type, etc.)
  - `max_depth` integer — Maximum tree depth to traverse (default: 10)
  - `beam_width` integer — Beam width for parallel exploration (default: 3)
  - `min_confidence` number — Minimum confidence to continue traversal (default: 0.3)
  - `limit` integer — Maximum results to return (default: 10)

## Response `200`

Search completed successfully

- SearchResponse
  - `results` SearchResult[] — Search results ordered by relevance
    - `node_id` string — Node ID where content was found
    - `document_id` string — Document ID containing this result
    - `path` PathNode[] — Path from root to this node (breadcrumbs)
      - `node_id` string
      - `title` string
      - `reasoning` string — LLM's reasoning for selecting this path
    - `content` string — The relevant content at this node
    - `answer` string — LLM's extracted answer (if applicable)
    - `confidence` number — Confidence score (0.0 to 1.0)
  - `stats` SearchStats
    - `nodes_visited` integer — Total nodes visited during traversal
    - `nodes_pruned` integer — Nodes pruned (not explored due to low confidence)
    - `llm_calls` integer — Number of LLM API calls made
    - `total_time_ms` integer — Total search time in milliseconds

## Other responses

- `422` — Validation failed
- `500` — Search failed

---

[API](https://skmtc.net/brainfish-ai/apis/reasondb-api.md) · [All operations](https://skmtc.net/brainfish-ai/apis/reasondb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brainfish-ai/reasondb-api/revisions/f8665c1a5239/schema)