Semantic mode needs agent:run. An answer requires confirmed evidence refs. Cancel returns insufficient evidence.

Last updated: 2026-11-05 Product area: Cookbook Page type: Tutorial

Search and Answer with the context policy lab open — Search and Answer is the collection screen. The HTTP examples are workspace search and require a confirmed evidence list before an answer.

Scoped search

Ask one question of the example collection and require a citation or an explicit miss. Hands-on time is about 25 minutes. Provider time on semantic mode and answers is extra.

Purpose

You can separate local search, semantic search, and a grounded answer. Level: editor with agent:run for semantic and answer calls. Mode: stored, collection Indexed. UI path: Search and answer. HTTP path below is different and must not be mixed quietly.

Prerequisites

collection:read and document:read. Semantic mode and /search/answer also need agent:run. Default search mode is local and does not call a provider.

Sample

Question: How many days is the Harbor Sample delivery window? Success shape: status grounded, a short answer, and a citation whose excerpt contains 14 days. Insufficient shape: status insufficient_evidence when you confirm a ref that does not support the question, or when you cancel.

Steps

On the collection Search tab, ask the question in Search only. You get ranked chunks, not an answer.
For HTTP, POST /api/w/{workspaceId}/search with mode local or semantic. Semantic checks agent:run again before the provider call.
Take evidenceRef values from the search evidence you intend to use. Rehydrate with POST /api/w/{workspaceId}/search/evidence if you need the current excerpt.
POST /api/w/{workspaceId}/search/answer with confirmed: true and those refs. confirmed must be the literal true. A false value is rejected by the schema.
Stop an in-flight answer by aborting the HTTP request. The body comes back insufficient_evidence with a null answer.

Fields

Field	Rule
`query`	1–500 characters.
`mode`	`local` (default) or `semantic`.
`collectionIds`	Optional uuid list, max 20. Omit to search the visible workspace scope.
`types`	Optional `document` and/or `smart_bite`, max 2.
`limit`	Integer 1–30, default 15.
`cursor`	Optional, max 500. Use `nextCursor` from the previous page.
`evidenceRefs`	1–12 strings, each 20–2000 characters, from the search you just ran.
Answer `status`	`grounded`, `insufficient_evidence`, `unavailable`, or `source_changed`.
`coverage.state`	`complete`, `partial`, or `unavailable`. Partial is not a full corpus claim.

Example

curl -sS -X POST "$BUNDATA_ORIGIN/api/w/$WORKSPACE_ID/search" \
  -H "Authorization: Bearer $BUNDATA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"How many days is the Harbor Sample delivery window?","mode":"local","limit":5}'

{"query":"How many days is the Harbor Sample delivery window?","confirmed":true,"evidenceRefs":["paste-the-evidence-ref-from-search"]}

The answer URL is /api/w/{workspaceId}/search/answer. Do not send a ref from another workspace.

Recovery

source_changed or SEARCH_EVIDENCE_STALE means the bite moved or expired. Search again and confirm the new refs. Do not reuse yesterday’s ref. 403 on semantic mode means agent:run is missing. A provider sentence without a citation is not success. unsupportedAspects names what the evidence did not cover.

Limits

Context Policy on the collection screen tunes the next UI run. It does not re-embed and it is not the body of /search. Eval Studio scores are a separate product area. This recipe does not call them.

Check

Success: grounded plus a citation excerpt with 14 days. Failure: cancel, or a ref that does not mention a window, returns insufficient_evidence and a null answer.