Ask

Grounded answers, their citations, which retrieval runtime answered, and when the system abstains.

How an answer is built

Ask retrieves regions from the active World and answers from them. Every answer carries the regions it used, with the source version, page and bounding box of each. The answer text is those regions' excerpts, concatenated in the order the retriever ranked them — answerMode is evidence_excerpts, and no language model writes any part of it. That is a deliberate boundary, not a gap waiting to be filled quietly: the day a model does generate an answer, answerMode will say a different word, and you will be able to tell from the response rather than from a changelog.

Abstention, and why it is a result

When no region matched the question, the response is an abstention with a reason. That is a result, not a failure: an answer with no evidence behind it is the failure. A region can also be retrieved and still not be citable — if it carries no evidence binding it is dropped, and an answer left with no citations abstains rather than claiming something no region supports.

Which runtime answered

Two retrieval runtimes can answer, and the response always says which one did. retrievalPath is the field; both values are real and neither is a placeholder.

The fallback is not a rare edge. A World activated before its index was compiled, a compile that failed on an unreachable embedder, and a run still in flight all land here, and the response distinguishes them: retrievalIndex.status is missing, compiled or failed, retrievalIndex.errorClass names the failure class, and retrievalNotice says the same thing in a sentence. An index that exists but has not finished is reported as missing — an incomplete index is not queryable, and half an index is not a smaller index.

Both paths return answer, reason, citations, receipt, activeWorld, freshness, answerMode and retrievalPath. What differs is the per-citation scoring, and it is not normalized across the two: the fallback reports relevance with its lexical, graph, temporal and authority breakdown, while the compiled path reports each source's rank and the reranker score. Presenting one as the other would mean inventing a number neither path measured.

The two paths differ in retrieval quality, so read retrievalPath before comparing answers across Worlds: a difference between two answers can be a difference between two runtimes rather than between two corpora.

The freshness clocks

Note A null in the freshness block means that value is not recorded, or could not be read. It is never a substitute drawn from one of the other clocks. candidateAwaitingActivation is also conservative: it is computed from versions the workspace has activated at least once, the manifest digest the latest compile recorded, and the candidate this request already loaded, so it can read false for a compile that ran before that digest was recorded.

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

import os
import requests

body = {
    "question": "<question>"
}

response = requests.request(
    "POST",
    "https://tavonel.com/api/v1/collections/{id}/ask",
    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}/ask", {
  method: "POST",
  headers: { authorization: `Bearer ${process.env.TAVONEL_API_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({ "question": "<question>" }),
});
if (!response.ok) throw new Error(`${response.status} ${(await response.json()).code}`);
console.log(await response.json());

{
  "question": "<question>"
}