# Quivr

> An open-source engine that turns continuous content streams into search and monitoring.

- [Quivr V2](https://docs.quivr.thevibecompany.co/index.md): The project overview: why Quivr, architecture, quickstart and what works today
- [Using Quivr](https://docs.quivr.thevibecompany.co/start/functional.md): What Quivr does, how to run it, and how to send it content to search and monitor. For integrators, operators and non-developers.
- [Public HTTP transport contract](https://docs.quivr.thevibecompany.co/contracts/http/v0/index.md): How the HTTP API contract is organised and checked
- [Quivr V2 — Remaining limits](https://docs.quivr.thevibecompany.co/quivr-v2-remaining-limits.md): Known limits and what is not claimed
- [What Quivr can do](https://docs.quivr.thevibecompany.co/what-quivr-can-do.md): What Quivr does, in plain words, for non-developers
- [API walkthrough](https://docs.quivr.thevibecompany.co/api-walkthrough.md): Endpoint behaviour, limits, processing and search in detail
- [Connect an AI agent](https://docs.quivr.thevibecompany.co/connect-an-ai-agent.md): Let an AI agent search Quivr, cite sources and add text over MCP
- [Connector Instances: operator guide](https://docs.quivr.thevibecompany.co/connectors/index.md): Set up and operate scheduled sources of content
- [Microsoft 365 mailbox (m365_mail): operator guide](https://docs.quivr.thevibecompany.co/connectors/microsoft-365.md): Collect mail from a Microsoft 365 mailbox
- [RSS and Atom feeds (rss)](https://docs.quivr.thevibecompany.co/connectors/rss.md): Collect articles from RSS and Atom feeds
- [X lists (x_list): operator guide](https://docs.quivr.thevibecompany.co/connectors/x.md): Collect posts from an X list
- [X lists in real time: webhook mode](https://docs.quivr.thevibecompany.co/connectors/x-webhooks.md): Receive the posts of an X list in real time through webhooks
- [Railway evaluation demo](https://docs.quivr.thevibecompany.co/deploy/railway/index.md): Run a hosted single-node evaluation demo
- [Described alerts: alerts written in plain language](https://docs.quivr.thevibecompany.co/described-alerts.md): Write alerts in plain language, and see what is sent to the model provider
- [Your first search](https://docs.quivr.thevibecompany.co/first-search.md): Create a Corpus, add a Record and search it, step by step
- [Keyword alerts: writing alert queries](https://docs.quivr.thevibecompany.co/keyword-alerts.md): Write alert queries and set up metadata filters
- [Quivr Search demo (THE-663)](https://docs.quivr.thevibecompany.co/quivr-search/index.md): The demo web app: search, sources and live feed
- [Command-line reference](https://docs.quivr.thevibecompany.co/reference/cli.md): Every quivr command, what it needs to run, its flags and exit codes
- [MCP reference](https://docs.quivr.thevibecompany.co/reference/mcp.md): Every MCP profile and tool an AI agent can use, with its arguments
- [Writing plugins](https://docs.quivr.thevibecompany.co/start/plugin-author.md): How to extend Quivr with your own plugins, for example a new file format or a new kind of alert rule.
- [Plugin Protocol v0](https://docs.quivr.thevibecompany.co/contracts/plugins/v0/index.md): The plugin manifest, routes, schemas and fixtures
- [alerts](https://docs.quivr.thevibecompany.co/plugins/alerts/index.md): The first-party keyword alert plugin
- [X list connector plugin (x-list)](https://docs.quivr.thevibecompany.co/plugins/x-list/index.md): The first-party X list connector plugin and its parity tests
- [pdf-text](https://docs.quivr.thevibecompany.co/plugins/pdf-text/index.md): The reference PDF normalizer, one Part per page
- [RSS and Atom connector plugin](https://docs.quivr.thevibecompany.co/plugins/rss/index.md): The first-party RSS and Atom connector plugin
- [Run a connector plugin](https://docs.quivr.thevibecompany.co/plugins/run-a-connector-plugin.md): Pin a connector plugin and read the health it reports
- [Write a normalizer](https://docs.quivr.thevibecompany.co/plugins/write-a-normalizer.md): From quivr plugin init to a searchable, observable Record
- [Write an ingestion plugin](https://docs.quivr.thevibecompany.co/plugins/write-an-ingestion-plugin.md): Decide how articles are cut and embedded, and move a Corpus onto it
- [Quivr Plugin SDK for Go](https://docs.quivr.thevibecompany.co/sdks/go/index.md): Write, test and certify a source collector or an ingestion plugin in Go
- [Quivr Plugin SDK for Python](https://docs.quivr.thevibecompany.co/sdks/python/index.md): Write, test and run a Python normalizer
- [Contributing to Quivr](https://docs.quivr.thevibecompany.co/start/contributor.md): How this repository is organised, tested and changed, for people and coding agents alike.
- [Quivr Ingestion and Retrieval](https://docs.quivr.thevibecompany.co/context.md): The domain language: Corpus, Record, Version, Manifest and the other terms
- [Quivr V2 — Local harness and operational baseline](https://docs.quivr.thevibecompany.co/quivr-v2-local-harness.md): How make dev and make verify work
- [Repository instructions](https://docs.quivr.thevibecompany.co/agents.md): Rules every contributor and coding agent follows in this repository
- [Documentation conventions](https://docs.quivr.thevibecompany.co/agents/documentation.md): Living and dated documents, the inventory, budgets and when docs may change
- [Domain documentation](https://docs.quivr.thevibecompany.co/agents/domain.md): How the domain documentation is laid out
- [Measure search quality](https://docs.quivr.thevibecompany.co/agents/evaluation.md): Measure how well search ranks results on public and private evaluation sets
- [Agent fleet workflow](https://docs.quivr.thevibecompany.co/agents/fleet-workflow.md): How parallel agents claim, plan and ship tickets
- [Issue tracker: Linear](https://docs.quivr.thevibecompany.co/agents/issue-tracker.md): How specs and tickets are written and tracked
- [Testing standard](https://docs.quivr.thevibecompany.co/agents/testing.md): What a good test looks like here
- [Triage labels](https://docs.quivr.thevibecompany.co/agents/triage-labels.md): The five triage labels
- [Runnable guide blocks](https://docs.quivr.thevibecompany.co/runnable-guides.md): Write guide blocks that make verify replays
- [Public acceptance suite](https://docs.quivr.thevibecompany.co/tests/acceptance/index.md): The public acceptance suite and how to run it
- [Dated documents](https://docs.quivr.thevibecompany.co/dated/index.md): Frozen design records, evidence and research, as decided at their date
- [Third-party notices and dependency inventory](https://docs.quivr.thevibecompany.co/third_party/index.md): Dependency notices and inventory
- [List records](https://docs.quivr.thevibecompany.co/api-reference/records/list-records.md): Stable keyset traversal of one Corpus's authorized canonical Records in Record ID order, including withdrawn Records. Each page is an independent read, not an atomic historical snapshot. Capture a start-now Change Cursor before scanning, then consume changes after it as invalidations by rereading cu…
- [Ingest record](https://docs.quivr.thevibecompany.co/api-reference/records/ingest-record.md): Commit durable input, Receipt and dispatch intent before responding. Same key and canonical request returns same Receipt; changed request conflicts. A new source revision corrects the Record. All accepted/replayed submissions use 202, even when a replayed Receipt has resolved.
- [Ingest batch](https://docs.quivr.thevibecompany.co/api-reference/records/ingest-batch.md): Initial bound: 100 entries (413 batch_too_large), envelope 10 MiB (413 request_too_large). Validate envelope structure/size first, then each entry independently against IngestCommand, including wrong types or missing fields. Each raw entry is also held to the 1 MiB single-request bound (entry error…
- [Withdraw record](https://docs.quivr.thevibecompany.co/api-reference/records/withdraw-record.md): Durably commit withdrawal and Receipt before responding. Terminal identity fence, including before first materialization; no physical purge and no cascade. Uses a distinct withdrawal route family.
- [Get record](https://docs.quivr.thevibecompany.co/api-reference/records/get-record.md): Authorized canonical currentness and withdrawal view.
- [Get version](https://docs.quivr.thevibecompany.co/api-reference/records/get-version.md): Authorized immutable source Manifest plus separate live availability and relation expansion. Available links supply current eligible target Record and Version IDs; unavailable links reveal no resolved target IDs or absence/access reason. Historical lookup grants no new rights.
- [Get receipt](https://docs.quivr.thevibecompany.co/api-reference/ingestion-receipts/get-receipt.md): Return outcome and separately authorized linked availability/diagnostics. Omit unavailable linked content rather than bypassing rights through the Receipt. Linked Version/Record details require current content:read permission and target Corpus authorization.
- [Create upload](https://docs.quivr.thevibecompany.co/api-reference/uploads/create-upload.md): Create a transfer session with a single presigned PUT URL, required headers and expiry. Initial limits: 1 GiB Blob, configurable; oversized uploads are rejected before a session is issued.
- [Confirm upload](https://docs.quivr.thevibecompany.co/api-reference/uploads/confirm-upload.md): Start or observe checksum/size verification; SDK polls until verified before referencing the Blob in ingestion. Confirmation is repeatable for this session.
- [Get upload](https://docs.quivr.thevibecompany.co/api-reference/uploads/get-upload.md): Observe upload verification independently of Ingestion Receipt.
- [Get blob](https://docs.quivr.thevibecompany.co/api-reference/blobs/get-blob.md): Inspect verified Blob metadata within authorized Organization scope; ID possession does not grant access.
- [Get operation](https://docs.quivr.thevibecompany.co/api-reference/operations/get-operation.md): Administrative progress only. This read schema does not specify every administrative command.
- [Cancel operation](https://docs.quivr.thevibecompany.co/api-reference/operations/cancel-operation.md): Idempotent cancellation request; does not undo committed effects. Terminal operation returns its existing state. A racing completion may win. Cancellation becomes terminal only after work stops safely; no partial active projection cutover.
- [Rerun operation](https://docs.quivr.thevibecompany.co/api-reference/operations/rerun-operation.md): Only terminal Operations can be intentionally rerun; otherwise 409 operation_not_terminal. A request key replays the same new linked Operation. Revalidate current scope and command eligibility; completed effects remain subject to domain idempotency.
- [List corpora](https://docs.quivr.thevibecompany.co/api-reference/corpora/list-corpora.md): Authorized Corpora only. Opaque page cursor bound to action/filter/scope; not a Change Cursor or a Record page cursor (either is 422 invalid_cursor).
- [Create corpus](https://docs.quivr.thevibecompany.co/api-reference/corpora/create-corpus.md): Explicit Corpus creation. Same creation route-family key and canonical request replays the same Corpus. Requires corpora:write.
- [Get corpus](https://docs.quivr.thevibecompany.co/api-reference/corpora/get-corpus.md): Read effective resolved configuration.
- [Configure retrieval](https://docs.quivr.thevibecompany.co/api-reference/corpora/configure-retrieval.md): Resolve mapping and schedule a new immutable Projection Generation through a retrieval_configuration Operation (202 with Location). Existing active config remains in effect, and is what getCorpus returns, until validated cutover; the Operation reports the pending config's progress and outcome but no…
- [List vector spaces](https://docs.quivr.thevibecompany.co/api-reference/corpora/list-vector-spaces.md): The vector spaces the Corpus's routed Projection Generation carries, the served one first, each with its owner (the engine, or the ingestion plugin that declares it), model, dimensions, metric, indexed and query modalities, its role in the generation (served answers search, evaluation is indexed and…
- [Rebuild corpus projection](https://docs.quivr.thevibecompany.co/api-reference/corpora/rebuild-corpus-projection.md): Durably commit a projection_rebuild Operation and dispatch intent before returning. Rebuild the requested Corpus from canonical text and durable artifacts, then activate its validated logical generation. Same Organization + Corpus + rebuild route + idempotency key and canonical request returns the s…
- [Poll changes](https://docs.quivr.thevibecompany.co/api-reference/changes/poll-changes.md): Same durable journal as SSE. Without cursor, return empty items and current committed position as next_cursor (start now). With cursor, return authorized events after it, in commit order; duplicates possible. Cursor binds Organization, Corpus filter and authorization scope. Expiry is 410 cursor_expi…
- [Stream changes](https://docs.quivr.thevibecompany.co/api-reference/changes/stream-changes.md): SSE over the same journal. Last-Event-ID takes precedence over query cursor on reconnect. id is an opaque Change Cursor; data.event_id is deduplication identity. Named change events carry ChangeEvent JSON. checkpoint events carry a cursor when no visible event is emitted, including initial start-now…
- [Create saved query](https://docs.quivr.thevibecompany.co/api-reference/saved-queries/create-saved-query.md): Persist definition and first immutable version. Replay same key/request returns same IDs; conflict on changed request. Query creation alone evaluates nothing.
- [Get saved query](https://docs.quivr.thevibecompany.co/api-reference/saved-queries/get-saved-query.md): Authorized current query view.
- [Get saved query version](https://docs.quivr.thevibecompany.co/api-reference/saved-queries/get-saved-query-version.md): Read any immutable Version of the Saved Query, current or earlier, such as the one a Subscription Version or Match pins. The key must grant the Corpora of the Saved Query's current Version and of this Version. A deleted Saved Query's Versions stay readable.
- [Create saved query version](https://docs.quivr.thevibecompany.co/api-reference/saved-queries/create-saved-query-version.md): Edit a Saved Query by committing a new immutable Version that becomes its current Version, with saved_query.updated in every Corpus of the previous and new scope. Subscriptions keep the Version they pin; a new Subscription Version moves one. The key must grant every Corpus of the current and new def…
- [Delete saved query](https://docs.quivr.thevibecompany.co/api-reference/saved-queries/delete-saved-query.md): Logically delete a Saved Query that no Subscription which is not deleted belongs to (409 saved_query_in_use otherwise), with saved_query.deleted per Corpus. It and its Versions stay readable with deleted true; it gets no new Version or Subscription. Repeat is idempotent and commits no event.
- [Rename saved query](https://docs.quivr.thevibecompany.co/api-reference/saved-queries/rename-saved-query.md): Change the display name of a Saved Query. The name belongs to the Saved Query, not to its immutable Versions, so no Version is created and no Subscription moves. A new name commits saved_query.renamed in every Corpus of the current Version; the same name commits nothing. Replay of the same key and r…
- [List subscriptions](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/list-subscriptions.md): Active (enabled, not deleted) Subscriptions of one Subscription Owner, or the global ones with owner=none, in stable Subscription ID order. Lists only Subscriptions the key sees, like every Subscription read. Stable keyset page cursor bound to the owner filter and key scope, not a Change Cursor. Qui…
- [Create subscription](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/create-subscription.md): Atomically create enabled Subscription/Version and activation boundary in commit-ordered journal. Evaluate future eligible transitions, not existing history. Replay same key/request returns same identity and does not reactivate a disabled Subscription. The evaluator must be installed (422 unsupporte…
- [Get subscription](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/get-subscription.md): Read enabled state and pinned current configuration.
- [Get subscription version](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/get-subscription-version.md): Read any immutable Version of the Subscription, current or earlier, such as the one a historical Match names. As for every read of a Subscription, its Matches and Deliveries, the key must grant every Corpus any of its Versions pinned. A deleted Subscription's Versions stay readable.
- [Create subscription version](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/create-subscription-version.md): Edit a Subscription by committing a new immutable Version that becomes current. It pins the current Version of the Subscription's own Saved Query (422 unknown_saved_query otherwise), an evaluator and a destination. It takes effect from its commit, recorded as its activation position with subscriptio…
- [Delete subscription](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/delete-subscription.md): Logically delete a Subscription for good, with subscription.deleted per Corpus. It is also disabled, with every disable guarantee - no new evaluation commit and no new Delivery Attempt admission (reason subscription_deleted); an in-flight attempt may complete. As for a disabled Subscription, a match…
- [Disable subscription](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/disable-subscription.md): Commit disable. Block new evaluation commits and new Delivery Attempt admissions, including queued retries and update notices. In-flight attempts may complete. A match.withdrawn notice for a Match of this Subscription is still committed with its pending Delivery, which makes no attempt until re-enab…
- [Enable subscription](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/enable-subscription.md): Commit re-enable of a disabled Subscription on the same Subscription Version. Evaluation resumes from this commit; changes made while disabled are never evaluated. Pending Deliveries parked by the disable become eligible again under the usual admission checks and keep their delivery window, except a…
- [Rename subscription](https://docs.quivr.thevibecompany.co/api-reference/subscriptions/rename-subscription.md): Change the display name of a Subscription. The name belongs to the Subscription, not to its immutable Versions, so no Version is created, evaluation and enabled state are unchanged, and its Matches and Deliveries stay attached. A new name commits subscription.renamed in every Corpus of the current V…
- [Preview subscription](https://docs.quivr.thevibecompany.co/api-reference/subscription-previews/preview-subscription.md): Dry run of a proposed Subscription. Runs the evaluator on the most recently accepted current eligible Record Versions of the Saved Query's Corpora, newest first, and returns what it would have matched. Nothing is written - no Saved Query, Subscription, Match, Delivery or event - and it is not idempo…
- [List matches](https://docs.quivr.thevibecompany.co/api-reference/matches/list-matches.md): Authorized historical Matches for a Subscription. Stable keyset page cursor, not a Change Cursor. Absence of a Match does not distinguish an evaluator still working from a negative result.
- [Get match](https://docs.quivr.thevibecompany.co/api-reference/matches/get-match.md): Authorized historical positive result, explanation and provenance. Recheck current access to Subscription and content; disabled state alone does not erase history. Historical content retention remains separate from search eligibility.
- [Get delivery](https://docs.quivr.thevibecompany.co/api-reference/deliveries/get-delivery.md): Read logical notification status and current admission view. Rights on the referenced Subscription/Corpus are still required for withdrawal-notice metadata.
- [List delivery attempts](https://docs.quivr.thevibecompany.co/api-reference/deliveries/list-delivery-attempts.md): Paginated append-only transport history, without secrets or receiver bodies.
- [List connectors](https://docs.quivr.thevibecompany.co/api-reference/connectors/list-connectors.md): Connector Instances of authorized Corpora, optionally filtered to one Corpus, in stable identifier order. Opaque page cursor bound to filter and scope; not a Change Cursor or another list page cursor (422 invalid_cursor).
- [Create connector](https://docs.quivr.thevibecompany.co/api-reference/connectors/create-connector.md): Create a Connector Instance bound to exactly one authorized Corpus and one Source Namespace. Kind-specific config and credential secret are validated against the kind's JSON Schema (see listConnectorKinds); a failure is 422 invalid_config or invalid_credential with field pointing at the offending me…
- [Get connector](https://docs.quivr.thevibecompany.co/api-reference/connectors/get-connector.md): Read configuration, credential metadata (never the secret) and the last evaluated Connector Health. Instances of other Organizations or unauthorized Corpora are 404.
- [Disable connector](https://docs.quivr.thevibecompany.co/api-reference/connectors/disable-connector.md): Commit disable. No new acquisition run is scheduled; an in-flight run cannot advance the Acquisition Checkpoint afterwards. Repeat is idempotent and disable is absorbing (no re-enable). Commits connector.disabled and connector.health_changed.
- [Replace connector credential](https://docs.quivr.thevibecompany.co/api-reference/connectors/replace-connector-credential.md): Deposit a new credential version to rotate the current one. The secret is encrypted at rest and never returned. Replaying the same key and request is idempotent; a different request under the same key is 409 idempotency_conflict. A disabled instance is 409 connector_disabled. Commits connector.crede…
- [Change connector schedule](https://docs.quivr.thevibecompany.co/api-reference/connectors/change-connector-schedule.md): Set the polling interval of an enabled instance. Setting the current value commits nothing, so repeating the request is harmless. A shorter interval pulls the next scheduled run in; a longer one applies after the run already scheduled. A disabled instance is 409 connector_disabled; an interval below…
- [Request connector run](https://docs.quivr.thevibecompany.co/api-reference/connectors/request-connector-run.md): Ask for an acquisition run now instead of at the next scheduled time, for example to check again a source that failed. The next run is pulled in, never pushed out, so repeating the request changes nothing and a run already in flight answers it. Rate limits still hold -- the run starts no sooner than…
- [Relay connector challenge](https://docs.quivr.thevibecompany.co/api-reference/connector-webhooks/relay-connector-challenge.md): Public webhook route of one Connector Instance whose kind declares the push mode; the address is its webhook_url. There is no API key; the connector plugin verifies the request (a signature, a challenge) with the Deposited Credential. A GET is typically a source's verification challenge, relayed to…
- [Relay connector delivery](https://docs.quivr.thevibecompany.co/api-reference/connector-webhooks/relay-connector-delivery.md): Relay one delivery the source sends to the Connector Instance. The core passes the raw request (a body of at most 1 MiB, lowercase headers) to the connector plugin, which verifies it and returns the items it carries. Items converge with those of pull runs on the same Receipts. Deliveries update heal…
- [List connector kinds](https://docs.quivr.thevibecompany.co/api-reference/connector-kinds/list-connector-kinds.md): Connector kinds enabled in this deployment, with the JSON Schemas that validate their config and credential secret, so clients can render configuration forms without knowing the kinds. credential_deposits tells whether this deployment accepts Deposited Credentials at all; when unavailable, any creat…
- [List plugin registrations](https://docs.quivr.thevibecompany.co/api-reference/admin/list-plugin-registrations.md): Every plugin version this deployment has registered, oldest first, with its endpoint, manifest digest, the roles its manifest declares and its state. Quivr never starts a plugin; the operator runs it at its endpoint. On first start the registry is seeded, as active registrations, from the plugins pi…
- [Get active pipeline plan](https://docs.quivr.thevibecompany.co/api-reference/admin/get-active-pipeline-plan.md): The active Pipeline Plan, an immutable mapping of every role of the deployment to the registration serving it. 404 not_found when no plan is active, because the startup configuration pins no plugin. Requires plugins:admin.
- [Search records](https://docs.quivr.thevibecompany.co/api-reference/search/search-records.md): 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. Profi…
- [Receive monitoring notification](https://docs.quivr.thevibecompany.co/api-reference/webhooks/receive-monitoring-notification.md): Receiver endpoint, not a Quivr API route. Verify Standard Webhooks v1 HMAC-SHA256 over webhook-id + dot + webhook-timestamp + dot + raw body before parsing. Timestamp refreshed per attempt; body event_id equals webhook-id. See monitoring contract for retry defaults.

## OpenAPI Specs

- [openapi](/openapi.yaml)