On this page
Generate answers and inspect their sources¶
In Work, select Search for ranked passages or Answer for generated text with sources. For API calls, use the endpoints below.
Read the results¶
POST /api/v1/spaces/{space_id}/searchreturns rankedsourcesafter transforms, retrieval and reranking.POST /api/v1/spaces/{space_id}/queryreturnsanswerandsources, with a query ID and execution data when available.POST /api/v1/spaces/{space_id}/query/streamreturns server-sent events. Usestageandcheckfor progress and optionaltokendeltas for provisional text. Read the answer, sources and outcome from the single finaldoneevent. A terminalerrorsignals failure.
Send JSON with a nonempty query and optional top_k (1–20, default 5).
Every call checks access to the space. See Integrate ContextBase
for credentials and request examples.
Filter source documents¶
metadata_filter filters on indexed fields from the space’s metadata
schema before ranking. Agent answers and graph_global generation
return 409 for filtered /query and /query/stream. Use
/search to retrieve passages in either case. Local graph retrieval
filters source passages and drops graph prose that cannot be attributed
to selected documents. If an attached BM25 or SPLADE index was built
without copying row metadata, rebuild the ContextBase side index with
POST /api/v1/spaces/{space_id}/storage/index before using that filter.
Open and cite sources¶
Show
textandlocatorwhen available. A verified locator can contain the document name, section path, page or a half-open Unicode character range. Show available bibliography as metadata and distinguish its URL from the download link.Keep
parent_textfrom hierarchical chunking andgraph_contextfrom graph retrieval apart from the excerpt. A score can be absent and applies only to its ranking.Read full canonical chunks with the chunk detail endpoint or MCP
fetch_source. For attached records and generated graph sources, display the text and identity from the response.
In Work, select Open fragment 1 or another numbered source.
Show context expands parent_text when available. Download
original is available when the document can be downloaded. Show on
the map opens the embedding map for the question.
Check a deadline in the equipment handbook. If the supporting passage is absent, adjust retrieval. If the source is correct and the deadline is wrong, inspect the generator’s context and instruction.
Grounded generation (llm)¶
Configure the space’s LLM and set generate to the llm node.
It receives the original question and retrieved context.
generation_instruction adds answer rules. Leave it blank for the
default prompt. model, api_base and temperature override fields
for generation and inherit provider authentication and other space settings.
{
"node": "llm",
"params": {
"generation_instruction": "State the required action and the deadline in separate lines."
}
}
Keep the rest of the pipeline when changing generate. With
"generate": null, ordinary queries can return sources and an empty
answer. A step that needs an unresolved model can return 409.
Search skips generation and still runs configured transforms and rerankers,
including model-backed ones.
For questions about themes across the whole corpus, see the Generate a global answer (graph_global) generator in Build and query a knowledge graph.
Check an answer before publishing it (rubric)¶
A live check binds one criterion of a published, immutable rubric
version to a pipeline. Create and publish the rubric, then add the
criterion under postgeneration. Each check has a unique UUID
id, a rubric_version_id and a criterion_key.
Enable a pipeline generator to run the check. When a space answers through
an agent graph, only the agent service generates the answer. The pipeline’s
postgeneration checks do not run on that answer. Selecting a newer rubric
version is an explicit change to the binding.
For a published JSON Schema criterion keyed deadline_format, add
the item below to the pipeline. Use a fresh id and replace the
example rubric_version_id with the published version UUID. The
item’s fields go directly under postgeneration.
{
"postgeneration": [
{
"node": "rubric",
"id": "3d875fca-1d6f-4016-bae9-4b4ab8ba23f7",
"rubric_version_id": "8d45cd86-8281-4a68-99ee-9b80ecbef22c",
"criterion_key": "deadline_format",
"on_failure": "observe"
}
]
}
Choose the criterion’s evaluator:
llmjudges a rule expressed in words. Set the check’s explicitjudgeconfiguration and use a model that can apply the rule.regexverifies a Unicode text pattern. Configurepattern,mode(search or full match),expect_matchand optional flagsignore_case,multilineanddotall.json_schemavalidates the answer as raw JSON. Supply the schema as string fieldschema_jsonfor dialect2020-12. Code fences and invalid JSON fail a format check. Schema reference keywords are rejected andformatis annotation only. Both deterministic kinds run without a model.
The result is pass, fail or unevaluable. Start with
on_failure="observe" (default) to see results, then decide which
criteria must control publication. Optional criteria continue regardless
of their result. An enforcing required criterion can block the
answer, regenerate from the same evidence, or
retrieve_regenerate with a new retrieval query. The per-node
max_retries applies across the entire original query and defaults
to zero. An enforcing check that cannot evaluate or has exhausted its
budget withholds the answer. Check outcome="blocked" in the final
response. Enforcing policies can hold token deltas until the platform
knows the outcome.
Verify the example on typical answers, then use block with a required
criterion if clients need JSON every time. Evaluate answer quality on a
full set of questions through Evaluate retrieval and answers.
Let an agent perform several searches¶
Agent presets offer a separate answer path that drives the space’s retrieval
pipeline. Configure a language model for the space. Try agent to let one
agent call search as needed. agent-wide adds tools for exact lexical
search and nearby passages.
agent-multistep splits routing, retrieval, synthesis and validation
among agents, with additional model calls. An agent answer may gather
evidence across several tool calls, giving the final sources no common
ranking score. Its stream can report stages with the full answer only
at the end. Compare its sources, latency and cost to a fixed pipeline
before changing the space’s answer path.
With a signed-in session, fetch the three presets from
GET /api/v1/pipeline/presets. Each includes a hybrid pipeline and an
agent_graph. Send the pipeline object as the body of
PUT /api/v1/spaces/{space_id}/config and wait for any required rebuild.
Then send the agent_graph object as the body of
PUT /api/v1/spaces/{space_id}/agent-graph. Keyword search tools require
a lexical leg. To fetch only the default single-agent graph, use
GET /api/v1/agent-graph/preset.