SEsenso
Search

Stream a grounded answer (SSE)

Like POST /org/search, but streams the result as Server-Sent Events: token events carry the answer as it is generated, a sources event then carries the matched chunks — each with the kb_node_id of its source document — and a final done event closes the stream. If answer generation fails to start, an error event is emitted instead (the HTTP status stays 200 because headers are already sent); a provider failure mid-stream ends the stream normally (sources + done) with a truncated answer. Each call consumes search credits.

post/org/search/stream

Request

  • Base URL
    https://apiv2.senso.ai/api/v1
  • Auth
    API key in header X-API-Key

Headers

X-Senso-Signalsstring

Send off to keep this search out of your organization's gap report. The search still runs, consumes credits and is recorded in search history; it is only never counted towards a gap. false, 0, no, skip and none mean the same, case-insensitively. Any other value, or no header, leaves the search eligible. Use it on automated, synthetic or test traffic. Only POST /org/search, /org/search/full and /org/search/stream ever file gaps; /org/search/context and /org/search/content accept the header and never file one either way.

Request body

querystring required

The search query. Required and non-empty; there is a maximum length.

max_resultsinteger

Maximum results to return. Defaults to 5; values ≤ 0 fall back to 5 and values above 20 are capped at 20.

content_idsstring[]

Restrict the search to these content items.

require_scoped_idsboolean

When true, content_ids must be non-empty — the request is rejected with 400 otherwise. Use it to guarantee a scoped search never silently widens.

search_typestring

Retrieval pipeline to use. One of hybrid (default), lexical, or vector. Matching is case-insensitive; an empty or omitted value selects hybrid. Any other value is rejected with 400.

neighbor_radiusinteger

/org/search/context only. Adds up to this many chunks either side of each matched chunk to results, marked inclusion_reason: "neighbor", so each match can be read as a passage. Defaults to 0 (matched chunks only); values outside 0–5 are rejected with 400. Total returned text is capped at about 60,000 characters, trimming the farthest neighbours first. Ignored by the other search endpoints, whose answers already include neighbouring chunks.

Response

A text/event-stream of SSE events: token ({"token": "..."}), then sources ({"results": [...], "total_results": N, "max_results": N, "search_type": "..."}, where each entry of results is a SearchResultChunk), then done ({}); or error ({"error": "..."}) on a post-open failure.

Changes

No recorded changes to this operation across all 1 revision of this API.