Vector Search
Search your uploaded files and get back the matching passages.
Hybrid retrieval: dense (embedding) and sparse (keyword) matches are fused with
reciprocal rank fusion, so exact terms and paraphrases both work. Results are
chunks, each with its file_id, score and stored metadata — ready to drop into a
prompt as context.
Narrow the search with file_ids, a filter on the metadata you supplied at
upload, or a date_from / date_to window. top_k defaults to 5 (max 50).
Without file_ids the search covers the key owner’s own files. file_ids may also
name another member’s files in the key’s org when the key owner’s role holds
files:read across the org; ids you cannot reach are ignored, and if none remain
the result is empty and nothing is billed.
Only files uploaded with embed are searchable. Each call embeds your query, so
it is a billed request — it counts against your rate limits and spend caps like
any inference call.
Authorizations
Enter your MeshAPI key (rsk_...) or, for the admin-keys endpoints, a dashboard session token — sent as Authorization: Bearer <token>.
Headers
Dated version of the API contract to pin this request to. Omit it and the request is served under 2026-08 — the oldest supported version, so an existing integration is never moved by a release. A malformed or unsupported value is rejected with 400 invalid_api_version rather than falling back silently. The version actually served is echoed as X-Mesh-Version on every response, including errors.
2026-08, 2026-09 Body
1 <= x <= 50Restrict to these file IDs
Match on any metadata key/value pairs
Unix timestamp — only chunks created after this
Unix timestamp — only chunks created before this
Your own labels for this request, echoed back on the usage row and available as a filter and a group-by dimension in the usage API. String keys to string values. Never put personal or sensitive data here — tags are stored with the usage record and are not redacted.
A stable, anonymised identifier for the end user making this request, recorded on the usage row and available as a filter and a group-by dimension in the usage API. Supersedes the deprecated user field. Use an opaque id, not an email address or a name.
256Response
Successful Response