Search

POST /v1/search runs the same hybrid retrieval as chat (dense bge-m3 vectors + keyword + reranking) but returns the ranked passages directly. It is fast and does not consume LLM tokens, which makes it ideal for type-ahead boxes, “related documents” panels and jumping to a node on the map.

interface SearchRequest { case: CaseId; query: string; topK?: number } // topK default 10
interface SearchResponse { results: Citation[] }

Results are Citation objects sorted by score (0..1), so you can reuse the same rendering as chat sources.

curl https://vol.example.com/api/v1/search \
  -H "X-API-Key: $VOL_API_KEY" -H "Content-Type: application/json" \
  -d '{"case":"cordis","query":"perovskite solar cells","topK":5}'

const { results } = await vol.search({ case: "cordis", query: "perovskite solar cells", topK: 5 });
for (const r of results) console.log(r.score.toFixed(2), r.title, r.nodeIndex);

r = requests.post(f"{BASE}/v1/search", headers=H,
                  json={"case": "cordis", "query": "perovskite solar cells", "topK": 5})
for hit in r.json()["results"]:
    print(round(hit["score"], 2), hit["title"], hit["nodeIndex"])

Tips

Debounce user input (250–400 ms) and ignore queries shorter than 3 characters.
Results are deduplicated per node: each row is a different document, with its best-matching passage.
To fly the 3D map to a result, pass its nodeIndex to the viewer.

React users can drop in <VolSearch>.