Skip to main content
POST
hybrid_search

Authorizations

X-API-Key
string
header
required

Path Parameters

workspace_id
string<uuid>
required

Workspace identifier.

Body

application/json

Request for hybrid-search, the workspace's one search method.

The retrieval configuration (legs, fusion) is fixed server-side — see tools.service.SEARCH_LEGS — so the body carries only the query and scope. path_prefix and categories are additive scope filters — omitting them means the whole workspace.

query
string
required
Required string length: 1 - 4096
categories
string[] | null
k
integer
default:10
Required range: 1 <= x <= 100
path_prefix
string | null

Response

Successful Response

Response of hybrid-search.

candidates_seen is the pre-access-filter count so the caller can tell when truncation happened upstream of the access gate.

Every hits[].path is an uploaded source path. Each hit also carries the ingestion derivative it was actually read from, but those fields are internal to the host (the agent tools address files that way) and are excluded from this body — a /v1 caller only ever sees the files it uploaded.

candidates_seen
integer
required
coverage
Coverage · object
required

What the access gate withheld, in counts and label names only.

Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request.

hits
Evidence · object[]
required
truncated
boolean
required