Skip to main content
POST
Search records

Authorizations

Authorization
string
header
required

API key, not necessarily a JWT. Server derives Organization, permitted actions and Corpus scope; every resource access is authorized.

Body

application/json

Text-only top-k query. Resolve all Corpora in the authenticated Organization and require read/search permission for every requested Corpus before querying. Never silently drop an unauthorized Corpus. Unknown/unsupported profile or mode returns 422; a dependency outage is an error, not an empty successful result. Query token limits are checked against the resolved profile; no silent truncation. An optional filter narrows candidates inside the engine query, before ranking and the limit, in every mode. Other metadata filters and pagination are outside this surface.

query
string
required

At most 8192 code points on the wire. A semantic or hybrid query is also limited by the owner of the searched vector space (the first-party core.ingest plugin accepts at most 256 tokens of its model's tokenizer); a longer query is refused with 422 query_too_long, whose message names the limit, never truncated.

Required string length: 1 - 8192
corpus_ids
string[]
required
Required array length: 1 - 16 elements
Minimum string length: 1
mode
enum<string>
default:hybrid
Available options:
lexical,
semantic,
hybrid
profile
string
default:default

A search profile this deployment answers (listSearchProfiles). The built-in path answers default only; a pinned retrieval plugin answers the profiles it declares, default among them. balanced is a deprecated alias of default, accepted through engine 0.1.x and removed in engine 0.2.0. An unknown profile returns 422 unsupported_profile.

Pattern: ^[a-z][a-z0-9_]{0,31}$
limit
integer
default:10
Required range: 1 <= x <= 50
filter
object

Candidate filter applied before ranking. Every present condition must hold. A requested Corpus served by a Projection Generation built before source filtering existed returns 422 source_filter_unavailable; rebuild that Corpus once (rebuildCorpusProjection) to enable it. Unfiltered search is unaffected.

Response

Successful response

Bounded top-k results after canonical rechecks. May contain fewer hits than requested; no total count, completeness promise or stable pagination snapshot. Empty results still name the resolved profile.

items
object[]
required
Maximum array length: 50
retrieval_profile
object
required

Resolved retrieval profile identity. Name is the profile that answered (default when the request named none or the deprecated balanced). Version identifies what ranked; the built-in path's immutable profile version, or plugin:@/ for a retrieval plugin.

usage
object

What a search answered by a retrieval plugin spent; rounds of the plugin, elapsed time, and the paid calls and cost the plugin reported.