Evidence availability and answer policies
Evidence availability and answer policies for Q integrations.
POST /v1/answer accepts evidence_policy. The final REST body, legacy complete.payload and version-1 machine completed.payload.result carry the same evidence and quality report. Wait for completion before accepting an answer. HTTP 200 and a grounding score alone do not establish evidence availability or claim accuracy.
{
"query": "What is our retention period?",
"mode": "ask",
"stream": true,
"stream_version": "1",
"evidence_policy": {
"mode": "strict",
"allowed_tools": ["keyword_search", "vector_search"],
"required_tools": ["keyword_search"]
}
}Choose a policy
| Policy | Behaviour |
|---|---|
auto (default) | Preserve useful evidence from successful sources. Failed optional sources make the answer partial. With no evidence and a retrieval failure, abstain. Successful empty retrieval can use the existing no-evidence response behaviour, labelled unverified. |
strict | Require selected, authorised evidence and no observed retrieval failures. Withhold provisional prose, citations and derived output until completion. If the requirements fail, return a deterministic abstention. |
general_knowledge | Skip retrieval planning and retrieval tools, return no retrieved sources or citations, and label the answer general_knowledge. This is an explicit request for an ungrounded answer, not a fallback that satisfies mandatory evidence. |
allowed_tools limits source channels. Omit it for the normal set; [] disables all tools in auto mode. required_tools requires evidence from every listed channel in the final selected sources, with no failure in that channel. A tool being called or returning a hit that is later discarded does not satisfy the requirement. A chunk found by both vector and keyword search retains both contributions through fusion.
Supported names are vector_search, keyword_search, retrieval_endpoint, federated_rag, web_search, fetch_url and mcp_search. Names must be unique. Required tools must be allowed. General knowledge cannot require tools; strict cannot allow an empty set. Invalid combinations receive HTTP 422.
An explicit policy (a non-auto mode, an allowlist or required tools) uses the guarded, primary retrieval/synthesis pipeline. ask and legacy quick, pro, deep tiers are accepted; deep keeps its retrieval settings but does not run iterative research under an explicit policy. agent, plan, debug and raw reject explicit policies. Default requests keep their existing routing. Legacy producers that do not supply evidence observations remain unknown/unverified.
Source selection does not grant access, enumerate private resources, force a planner to invoke a tool, or select individual provider URLs/documents. It constrains retrieval tools and disables implicit memory and codebase lookups. It does not restrict caller-provided history or explicit context. Strict evidence is a retrieval requirement, not proof that every generated claim follows from those sources.
Read the result
evidence.status describes availability; evidence.answer_status describes how to use the answer.
| Availability | Meaning |
|---|---|
available | Selected authorised evidence, no observed source failures. |
absent | Retrieval/selection was assessed and yielded no usable evidence, without an observed failure. |
partial | Useful selected evidence and at least one unavailable or missing required component. |
unavailable | No selected evidence and at least one failure or missing required component. |
not_requested | Explicit general knowledge. |
unknown | The producer has not measured evidence availability. |
Answer status is evidence_backed, partial, general_knowledge, unverified or abstained. An abstention replaces generated prose and removes citations, verification claims, grounding scores, follow-ups and derived artefact metadata. Authorised source results may remain for diagnosis. A permission recheck that loses a selected source discards all prose and sources derived from that selection.
Each bounded outcomes entry has a tool name, state, safe code, result count and retryability. Counts describe the observed tool result, not unique documents across tools or a sum across attempts. Several outcomes can record distinct failures of the same channel; a later success does not erase an earlier failure in the request.
| Code | Interpretation |
|---|---|
matched | The tool returned candidates; final selection may still filter them. |
empty_corpus | No live chunks are visible in the caller's tenant/Space/document-type scope. Hidden documents are indistinguishable from none. |
no_relevant_hit | Successful empty match; local retrieval has a visible corpus. External tools cannot infer whether their corpus is empty. |
timeout, cancelled | Retrieval did not finish; a retrieval budget cutoff also records timeout. Request-level cancellation/deadlines still follow the terminal failure contract. |
embedding_configuration_invalid, embedding_unavailable | Invalid embedding setup/compatibility, or unavailable embedding dependency. |
not_configured, provider_unavailable | No provider configured, or provider failure. An external HTTP 404 is unavailable, not an empty search. |
access_denied, permission_unavailable | Evidence access was lost/rejected, or permission state could not be checked. |
not_attempted | A required channel was not observed. |
quality remains the shared completeness/degradation contract. Missing required evidence makes completeness partial, even after a successful empty search. Safe typed issues replace provider exception text. Authentication, request validation, preflight and run-level failures continue to use the error contract.
Python exposes EvidencePolicy, EvidenceReport and RetrievalOutcome; q.answer.create, events, collect and legacy streaming accept either a policy dictionary or EvidencePolicy. TypeScript exports the same types and typed AnswerOptions.evidence_policy; Go exposes AnswerRequest.EvidencePolicy and AnswerResponse.Evidence. Omitted reports from older servers default to unknown in Python and remain omitted in TypeScript/Go; never infer success from omission.
See machine streaming, retrieval permissions and embedding compatibility. Qualification is local and synthetic; production query plans, providers, publication and deployed-version matching remain rollout work.