Search

Hybrid retrieval — lexical, dense and structure, RRF-fused and reranked — over the active World.

What Search runs against

Search runs against the active version. A workspace with no activated World returns nothing rather than falling back to a candidate — an answer from a version nobody accepted is not a smaller answer, it is a different one.

The pipeline, source by source

Three retrieval sources run concurrently over the World's compiled index: lexical full-text, dense vectors, and structure (claim and entity overlap with what the query already matched). Their ranks are fused with reciprocal rank fusion — ranks only, so native scores from different scoring spaces never mix — then reranked, then filtered by the World Gate, which admits a region only if it belongs to your tenant, to the active world version, and is bound to evidence.

The fields that say what ran

A degradation is reported, never hidden. dense retrieval skipped: no embedder configured means the answer came from lexical and structure alone; a reranker outage returns the fused order and says so. Reading degradations is how you tell a full-pipeline result from a partial one — the two otherwise look identical.

When there is no compiled index

Note Search requires a compiled retrieval index for the active World. Without one the response is 409 with the code RETRIEVAL_RUN_NOT_FOUND (or RETRIEVAL_PROFILE_NOT_FOUND), carrying retrievalIndex and retrievalNotice to say which state the index is in. It is not a 200 with fewer results: Search has no fallback, and a weaker answer presented as the real one is worse than a refusal you can act on. POST /v1/collections/{id}/retrieval-index rebuilds the index. It takes the collections:compile scope, the owner or admin role, and the same plan bar activating a World takes: Team, or Developer held by the workspace owner. The two bars are identical on purpose — this endpoint is the recovery path for an activation whose index did not compile, so a plan that may activate and may not rebuild would leave its own Worlds answering from the fallback with nothing to call.

curl -sS -X POST https://tavonel.com/api/v1/collections/{id}/search \
  -H "Authorization: Bearer $TAVONEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "query": "<query>", "limit": 1 }'

import os
import requests

body = {
    "query": "<query>",
    "limit": 1
}

response = requests.request(
    "POST",
    "https://tavonel.com/api/v1/collections/{id}/search",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    json=body,
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/collections/{id}/search", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({ "query": "<query>", "limit": 1 }),
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

{
  "query": "<query>",
  "limit": 1
}

Rebuilding the index

Rebuilding is a no-op that returns alreadyCompiled: true when a completed run for that World version already exists, so it is safe to call before a search rather than only after one fails. The manifest comes from the active pointer, which is why this cannot index a candidate nobody activated. A rebuild that does not reach a queryable index answers 503 with RETRIEVAL_INDEX_NOT_COMPILED and the failure class in retrievalIndex.errorClass — never a 200 over a half-built index, because half an index is not a smaller index.

curl -sS -X POST https://tavonel.com/api/v1/collections/{id}/retrieval-index \
  -H "Authorization: Bearer $TAVONEL_API_KEY"

import os
import requests

response = requests.request(
    "POST",
    "https://tavonel.com/api/v1/collections/{id}/retrieval-index",
    headers={"Authorization": "Bearer " + os.environ["TAVONEL_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://tavonel.com/api/v1/collections/{id}/retrieval-index", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());