POST /v0/search returns each matching document once with its best passage through the default retrieval plugin, across up to 16 Corpora, with the exact excerpt of each. This page covers the options you will use; the API reference lists every endpoint and field.
Prerequisites
QUIVR_API_URLand aQUIVR_API_KEYwithcontent:readandsearch:queryon the Corpora you search (Quickstart). The setup below also creates a Corpus and articles, which needscorpora:writeandcontent:writeon every Corpus, as the keyeval "$(make -s env)"exports does.- Some articles. These examples use a Corpus with two, from two sources:
receipt has a receipt_id: read GET /v0/ingestion-receipts/{receipt_id} until availability.searchable is true, as Add content shows. If availability.state reads quarantined instead, the article is on hold until an operator reprocesses it; If you can’t find it lists the other cases.
Choose a mode
When served vectors are unavailable, hybrid search returns keyword results with
retrieval_profile.degraded. An entry whose reason is vectors_unavailable
names the affected collections in corpus_ids, even when no documents match.
Other collections keep their hybrid results. You can show this notice until a
later response omits the marker; rebuilding needs no client-side retry loop.
An explicit semantic request has no keyword fallback. A collection with eligible
documents returns 422 unsupported_search when served vectors are unavailable.
With no eligible documents, including after the last Record is withdrawn, it
returns empty results. Stale or unknown coverage counts
alone do not disable a valid vector route. Model, index and storage outages
keep their error responses; they do not become keyword-only successes.
limit is 10 by default and 50 at most. There is no pagination: ask for what you will show.
A query has at most 8,192 characters. When vector search runs, the embedding model also caps its length (256 tokens with the first-party model); a longer query is refused with 422 query_too_long, never truncated.
Narrow to some sources
filter.source_namespaces keeps only Records from those Source Namespaces. The filter applies before ranking, so you get a source’s best matches even when other sources would outrank them:
Search one item at a time
The default retrieval plugin groups matching passages by document (Record in the API). Three matching passages still produce one result. Hybrid scoring combines one keyword score with the strongest passage-vector score. It highlights that vector passage; lexical search highlights the passage covering the most query terms. Highlights come from a bounded candidate window; exceptionally long documents can limit passage selection. Custom retrieval plugins can request individual passages. New Corpora index keyword fields once per document. Existing Corpora keep their keyword index until you rebuild them. Configure field weights through configureRetrieval, which builds a replacement index and activates it when ready; a separate rebuild is unnecessary. CallPUT /v0/corpora/{corpus_id}/retrieval with corpora:write
and operations:write on that Corpus. The linked reference describes the full
request and the Operation returned for monitoring progress.
For example (not run), these retrieval fields favor titles and add a French keyword copy of the body:
part_role; part_key_prefix narrows it, such as slugline- or paragraph-.
A source_pointer instead selects declared metadata. For a structured metadata
array, use type: "string_array"; value_pointer selects labels from each member,
for example /names (a string or array of strings).
Use the roles, keys and metadata namespaces your normalizer emits.
An analyzer adds a second keyword copy of a field, analyzed the same way at
ingestion and query time. Canonical excerpts and vector input keep their original
text. Omit it to index the field only as written. Quivr ships two analyzers:
Exact and analyzed matches contribute one keyword score; hybrid search combines it
with the strongest passage-vector score. The highlighted passage is the one with the
most query terms under the fields’ analyzers, or under
folded when no field names one.
To support another language, add an analyzer to Quivr itself:
- Add an entry to the
analyzerslist ininternal/keywords/keywords.go: theNamethe API accepts, aPropertysuffix no other analyzer uses, and a function that turns text into space-separated terms. Start fromfoldand add the language’s stopwords or stemmer, asfrench_light.godoes. - Add the name to the
analyzerenum ofFieldMappingincontracts/http/v0/openapi.yaml, then runmake generateandmake docs-site. - Add rows for the analyzer to the table in
internal/keywords/keywords_test.go.
Property or the output of a released analyzer: Corpora indexed
with it would stop matching new queries until you rebuild them.
You can narrow search to known identities using filter.record_ids and
filter.version_ids, each a nonempty array of up to 50 distinct IDs. Both conditions must hold;
a Version filter still returns only current, authorized content. Record identity
filters require rebuilding older Corpora; otherwise search returns
422 metadata_filter_unavailable.
Filter by document metadata
Sources can fill the commonquivr.metadata extension, schema version "1".
Use filter.metadata to compare these values across Corpora before ranking.
Common filter names start with metadata.:
Common strings are nonempty and contain at most 200 characters; common arrays
contain at most 50 strings. Unknown source values are omitted. For example, a document without a language
never matches a language filter. Sources retain their original metadata in their
own extensions alongside these common fields.
Each predicate names a
field and an any_of array. One value means equality;
several mean any-of equality. Array fields match any element. You can also set
inclusive gte and lte datetime bounds. New or rebuilt indexes use a range
index for dates. All predicates and all conditions
inside one predicate must hold. Datetimes use UTC millisecond precision;
submillisecond digits are truncated. Strings compare exactly, including case
and whitespace. A request has at most 16 predicates, 50 values per predicate,
and 200 characters per string value. Each field appears once.
For example (not run), this filter combines language and publication date:
filter. The same conditions work in
lexical, semantic and hybrid modes, including profiles that call other profiles.
For a Corpus-specific field, declare a typed retrieval mapping with the
filter role through configureRetrieval.
The mapping becomes usable when its rebuild succeeds. Common fields are
always declared. A requested field without the filter role excludes that
Corpus; excluded_corpora lists its corpus_id and the missing fields.
Eligible Corpora still contribute their matching documents. When every Corpus
is excluded, the response contains an empty items array.
Incompatible filter values return 422 invalid_query.
GET /v0/records accepts the same predicate array as JSON in the URL-encoded
metadata parameter. Select one Corpus with corpus_id, or up to 16 with the
comma-separated corpus_ids parameter, and use order=accepted_at_desc for
current acceptance date order. Filtering happens before pagination. The catalog
matches current Versions projected in the routed generation. A withdrawn
Record can disappear from filtered pages after its projection is purged or
rebuilt. Use the unfiltered catalog for complete resynchronization, including
withdrawn Records. Repeat the same selection and
predicates on every page, passing the response’s next_page_cursor as the next
request’s page_cursor. Stop when next_page_cursor is absent.
Metadata equality and datetime ranges use indexes scoped to the selected Corpus
and routed generation. If the bounded read cannot complete a page, Quivr returns
422 filter_too_broad with retryable: false and no partial page. Narrow the
metadata or acceptance-time range before trying again.
Changing the order, a filter, scope or routed generation returns
409 cursor_scope_changed; restart the listing. Search and listing filters on
older indexes return 422 metadata_filter_unavailable; rebuild those Corpora
with rebuildCorpusProjection first.
Count values for facets
POST /v0/facets counts documents with each metadata value in the selected
Corpora. It needs content:read on every requested Corpus. Reuse the
filter.metadata and filter.source_namespaces predicates from search; the
acceptance-time bounds from listing work here too. The example articles above
both declare English:
interval: "day", "month" or "year" for a date field such as
metadata.published_at. Buckets start at midnight UTC and omit empty periods.
The most frequent buckets are selected first, then dates are returned earliest
first. Custom fields need the Corpus’s filter mapping role; a Corpus missing
any requested field appears in excluded_corpora, just as with metadata
filters. If all selected Corpora are excluded, each requested field has empty
buckets. Older indexes need a rebuild. The
countFacets reference lists the bounds
and errors.
Exact counts read every current document, so they slow down as a corpus grows:
on a million documents they can take longer than the 25-second limit. Add
"accuracy": "fast" when a quick answer matters more than an exact one, as in a
filter sidebar. It is best effort: answers usually come within a few seconds,
and the 25-second limit still applies. Quivr then says how it counted:
Show estimates and stored counts as such, for example ”≈ 1,200” or “counted
4 minutes ago”. If you need exact numbers, request them again without
accuracy.
Cite a result
Each hit carries what a citation needs:GET /v0/records/{record_id}/versions/{version_id} returns the whole Version, so you can show the passage in context. Every hit is re-read from storage and re-checked against the caller’s access before it is returned. A search never returns a withdrawn Record, a Version that is no longer current, or a Corpus outside the key’s scope; a Corpus you may not read makes the whole search fail with 403.
Choose a profile
A profile names how results are found and ranked. Each installed retrieval plugin declares profiles. The deployment maps short names such asdefault and deep to full names such as core.retrieve/default; Search profiles explains the names and how one profile can re-rank another’s results. With one plugin and no map, its existing short names keep working. List them:
full_name, aliases and provider for every profile.
Pass a short name in profile. retrieval_profile.name echoes the name you sent, and usage.profiles lists the full name of each profile that ran:
make dev stack, where deep maps to core.retrieve/deep. An unknown profile is refused with 422 unsupported_profile.
Retry a busy search
Each API process admits at most 64 active searches across callers. When capacity is full, it returns503 search_unavailable with retryable: true and a Retry-After header. Wait at least that many seconds before retrying, and limit concurrent searches in your client. A dependency outage can return the same code without the header; use bounded backoff for those failures. The API overview describes the error envelope.
If Quivr cannot encode the query because its model is unavailable or times out, it returns retryable 503 model_unavailable. Retry with increasing delays and stop at your client’s retry deadline, or try lexical if the profile supports it. Query length limits still return 422 query_too_long.
Search from the command line
quivr search sends the same request from a terminal, with the same QUIVR_API_URL and QUIVR_API_KEY:
--json to print the API response unchanged, and --source to filter by Source Namespace. The CLI reference lists every flag and exit code.