> ## Documentation Index > Fetch the complete documentation index at: https://docs.quivr.thevibecompany.co/llms.txt > Use this file to discover all available pages before exploring further. # Search records > Resolve the requested profile, compile mandatory Corpus/Organization prefilters and any requested filter, obtain candidates, then canonically hydrate and reauthorize every returned segment. Lexical-first records remain eligible without embeddings; semantic-only queries require vector coverage. Profile selection does not change access/currentness rules. When a retrieval plugin is pinned, it ranks. It asks the engine for candidates in up to three rounds and returns its ranking, which may hold only candidates the engine served in this search, each already authorized and hydrated. ## OpenAPI ````yaml /openapi.yaml post /v0/search openapi: 3.1.0 info: title: Quivr V2 public text foundation contract version: 0.0.0-draft description: >- THE-543 and THE-547 evaluation contracts; endpoint implementations are separate work. Matching criterion is plugin-owned and deferred. One configured webhook destination, immutable Matches, independent at-least-once Delivery and reference-only notifications. OpenAPI is authoritative for transport shapes. THE-640 adds text search and asynchronous Corpus projection rebuild initiation. servers: [] security: - ApiKey: [] paths: /v0/search: post: tags: - Search summary: Search records description: >- Resolve the requested profile, compile mandatory Corpus/Organization prefilters and any requested filter, obtain candidates, then canonically hydrate and reauthorize every returned segment. Lexical-first records remain eligible without embeddings; semantic-only queries require vector coverage. Profile selection does not change access/currentness rules. When a retrieval plugin is pinned, it ranks. It asks the engine for candidates in up to three rounds and returns its ranking, which may hold only candidates the engine served in this search, each already authorized and hydrated. operationId: searchRecords requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' default: description: >- Structured error; 400 malformed, 401 unauthenticated, 403 unauthorized scope/action, 404 absent/inaccessible, 409 idempotency conflict, 422 unsupported_profile, query_too_long (the query is over the profile's or the vector space owner's length limit; the message names it), unsupported_search or source_filter_unavailable, 502 retrieval_plugin_invalid (the retrieval plugin broke its contract, for example ranked a segment the engine never served it), 503 dependency unavailable, 504 search_deadline_exceeded (the search outran its profile's max_latency_ms). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SearchRequest: type: object additionalProperties: false properties: query: type: string minLength: 1 maxLength: 8192 description: >- 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. corpus_ids: type: array items: type: string minLength: 1 minItems: 1 maxItems: 16 uniqueItems: true mode: type: string enum: - lexical - semantic - hybrid default: hybrid profile: type: string pattern: ^[a-z][a-z0-9_]{0,31}$ default: default description: >- 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. limit: type: integer minimum: 1 maximum: 50 default: 10 filter: $ref: '#/components/schemas/SearchFilter' required: - query - corpus_ids description: >- 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. SearchResponse: type: object additionalProperties: false properties: items: type: array items: $ref: '#/components/schemas/SearchHit' maxItems: 50 retrieval_profile: $ref: '#/components/schemas/SearchProfile' usage: $ref: '#/components/schemas/SearchUsage' required: - items - retrieval_profile description: >- 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. Error: type: object additionalProperties: false properties: code: type: string minLength: 1 message: type: string minLength: 1 retryable: type: boolean field: type: string minLength: 1 description: >- JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for example /config/url or /credential/secret/token on connector commands). resync_url: type: string format: uri-reference required: - code - message - retryable SearchFilter: type: object additionalProperties: false minProperties: 1 properties: source_namespaces: type: array items: type: string minLength: 1 maxLength: 200 minItems: 1 maxItems: 50 uniqueItems: true description: >- Keep only Records whose Source Namespace is one of these values. Ranking and the limit apply within the filtered set, so a source's best matches are returned even when other sources outrank them. description: >- 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. SearchHit: type: object additionalProperties: false properties: record_id: type: string minLength: 1 version_id: type: string minLength: 1 part_key: type: string minLength: 1 segment_id: type: string minLength: 1 segmentation_id: type: string minLength: 1 projection_generation_id: type: string minLength: 1 embedding_artifact_id: type: string minLength: 1 vector_space_id: type: string minLength: 1 rank: type: integer minimum: 1 excerpt: $ref: '#/components/schemas/SearchExcerpt' availability: $ref: '#/components/schemas/Availability' explanation: type: string minLength: 1 maxLength: 1024 description: Why the retrieval plugin ranked this hit here, when it says so. required: - record_id - version_id - part_key - segment_id - segmentation_id - projection_generation_id - rank - excerpt - availability description: >- One authorized segment hit. Rehydrate from canonical storage and recheck Organization/Corpus access, currentness, quarantine and Tombstone before returning. Rank is contiguous and one-based after hydration/filtering. Projection Generation, segmentation, segment and optional Embedding Artifact/Vector Space are logical durable IDs, not physical collection names or workflow IDs. Embedding references are omitted when that segment has lexical coverage only. They do not assert that the dense branch contributed to its rank. All hits inherit the response retrieval profile. Raw scores/explainScore stay internal. if: required: - embedding_artifact_id then: required: - vector_space_id else: not: required: - vector_space_id SearchProfile: type: object additionalProperties: false properties: name: type: string minLength: 1 version: type: string minLength: 1 required: - name - version description: >- 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. SearchUsage: type: object additionalProperties: false properties: rounds: type: integer minimum: 1 maximum: 3 elapsed_ms: type: integer minimum: 0 paid_calls: type: integer minimum: 0 cost_cents: type: number minimum: 0 required: - rounds - elapsed_ms - paid_calls - cost_cents description: >- What a search answered by a retrieval plugin spent; rounds of the plugin, elapsed time, and the paid calls and cost the plugin reported. SearchExcerpt: type: object additionalProperties: false properties: text: type: string maxLength: 4096 start: type: integer minimum: 0 end: type: integer minimum: 0 coordinate_system: type: string enum: - unicode_codepoint required: - text - start - end - coordinate_system description: >- Exact canonical normalized Part text slice [start,end), using Unicode code points, not UTF-8 bytes or UTF-16 units. End must be >= start and end-start must equal the excerpt code-point length. Bounds are checked against the referenced immutable Part. No synthetic highlights or rewritten snippets. Availability: type: object additionalProperties: false properties: state: type: string enum: - materialized - building_baseline - retrieval_ready - quarantined is_current: type: boolean searchable: type: boolean required: - state - is_current - searchable securitySchemes: ApiKey: type: http scheme: bearer description: >- API key, not necessarily a JWT. Server derives Organization, permitted actions and Corpus scope; every resource access is authorized. ````