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}/search returns ranked sources after transforms, retrieval and reranking.

  • POST /api/v1/spaces/{space_id}/query returns answer and sources, with a query ID and execution data when available.

  • POST /api/v1/spaces/{space_id}/query/stream returns server-sent events. Use stage and check for progress and optional token deltas for provisional text. Read the answer, sources and outcome from the single final done event. A terminal error signals 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 text and locator when 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_text from hierarchical chunking and graph_context from 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.

Filter support · Source fields · Stream events

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.

Implementation

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:

  • llm judges a rule expressed in words. Set the check’s explicit judge configuration and use a model that can apply the rule.

  • regex verifies a Unicode text pattern. Configure pattern, mode (search or full match), expect_match and optional flags ignore_case, multiline and dotall.

  • json_schema validates the answer as raw JSON. Supply the schema as string field schema_json for dialect 2020-12. Code fences and invalid JSON fail a format check. Schema reference keywords are rejected and format is 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.

Check configuration · Publication logic

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.

Agent graph configuration · Agent runtime

ContextBase0.1.0

Search the documentation