Plugin protocol

The HTTP routes a plugin serves, with every field of their JSON bodies, the error envelope and the fixture files quivr plugin test reads. A plugin serves JSON over HTTP; every route is under /v0, the major version of the Plugin API. The schemas in contracts/plugins/v0/ are the source of truth; the SDKs and quivr plugin test implement them.

Discovery and health

`GET /v0/discovery`

manifest_digest is sha256 over the exact bytes of the quivr-plugin.yaml the plugin was built from; the engine compares it with the pinned manifest. Response body (200) (discovery.schema.json)

Field	Type	Required	Description
`plugin_api`	string	yes	Plugin API version the plugin implements.
`plugin`	object	yes	—
`plugin.id`	`PluginId` (shared Manifest schema)	yes	—
`plugin.version`	`Version` (shared Manifest schema)	yes	—
`manifest_digest`	string	yes	—
`contributions`	array of `normalizer`, `subscription`, `connector`, `ingestion`, `retrieval`	yes	—

`GET /v0/health`

Returns 200 with this body when the plugin can accept invocations; otherwise 503 with the error envelope. Response body (200) (health.schema.json)

Field	Type	Required	Description
`status`	`"ok"`	yes	—

Normalizer

`POST /v0/contributions/normalizer`

Immutable invocation context plus a reference to the input Blob; bodies are never inline. Request body (normalizer-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`idempotency_key`	string	yes	Opaque, stable across retries of the same logical invocation. The same key must yield the same logical output. 1 to 256 characters.
`contribution`	`"normalizer"`	yes	—
`organization_id`	string	yes	—
`corpus_id`	string	yes	—
`record_id`	string	yes	—
`record_version_id`	string	yes	—
`source`	`SourceIdentity` (shared Manifest schema)	yes	Source namespace and Record Key of the Record.
`input`	object	yes	—
`input.blob_id`	string	yes	—
`input.media_type`	string	yes	At most 255 characters.
`input.size_bytes`	integer	yes	—
`input.sha256`	string	yes	—
`input.reference`	object	yes	—
`extensions`	`Extensions` (shared Manifest schema)	no	Extensions submitted with the Record Version.
`provenance`	`Provenance` (shared Manifest schema)	no	Provenance submitted with the Record Version.
`configuration`	object	yes	Installer configuration, already validated against the manifest configuration schema.

Response body (200) (normalizer-response.schema.json)

Field	Type	Required	Description
`manifest`	`ManifestContent` (shared Manifest schema)	yes	—
`extensions`	`Extensions` (shared Manifest schema)	no	Record Version extensions, only in namespaces the plugin declares.
`language`	string	no	BCP 47 language tag of the normalized content.
`warnings`	array of object	no	At most 32 items.
`warnings[].code`	string	yes	At most 64 characters.
`warnings[].message`	string	yes	1 to 1024 characters.

Alert rule (`subscription`)

`POST /v0/contributions/subscription`

Since Plugin API 0.2. One Record Version’s text Parts and metadata (source identity, acceptance time, provenance, extensions) and a batch of distinct evaluations to decide. The core deduplicates Subscriptions that share the same expression and configuration into one evaluation and never sends more evaluations than the manifest’s max_batch_size. Request body (subscription-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`idempotency_key`	string	yes	Opaque, stable across retries of the same logical invocation. The same key must yield the same decisions and evidence. 1 to 256 characters.
`contribution`	`"subscription"`	yes	—
`organization_id`	string	yes	—
`record`	object	yes	The evaluated Record Version.
`record.corpus_id`	string	yes	—
`record.record_id`	string	yes	—
`record.record_version_id`	string	yes	—
`record.enriched`	boolean	yes	True when the Version has embedding coverage in the active generation. A rule that needs enrichment answers not_ready while it is false; the core evaluates again after enrichment.
`record.parts`	array of object	yes	The canonical text Parts of the Version, in Manifest order. Blob Parts are not sent. Keys are unique. At most 256 items.
`record.parts[].key`	string	yes	—
`record.parts[].role`	string	yes	—
`record.parts[].text`	string	yes	—
`record.parts[].vector`	reserved	no	Reserved: a document that sets it is rejected.
`record.source`	object	no	Where the Record comes from: its Source Namespace and Record Key, and the Source Position of the accepted revision when the producer sent one. Always sent by the core since Plugin API 0.2.
`record.source.namespace`	string	yes	—
`record.source.record_key`	string	yes	—
`record.source.position`	string	no	Opaque source ordering value (for example a feed timestamp or a mail change key).
`record.accepted_at`	string	no	When Quivr accepted the revision this Version publishes (RFC 3339, UTC). Always sent by the core since Plugin API 0.2.
`record.provenance`	object	no	Who produced the Version. Always sent by the core since Plugin API 0.2.
`record.provenance.origin`	`client`, `connector`	yes	connector for a revision a Connector Instance acquired, client for one an API client submitted. A client cannot claim connector.
`record.provenance.producer`	string	no	The producer the client declared, or the Connector Instance id.
`record.provenance.producer_version`	string	no	—
`record.provenance.connector`	object	no	Present when origin is connector.
`record.provenance.normalization`	object	no	Present when an external normalizer produced the published Manifest.
`record.extensions`	`Extensions` (shared Manifest schema)	no	The Version’s structured metadata by namespace (for example author, section or categories when the source provides them). Absent when the Version has none.
`evaluations`	array of object	yes	Distinct evaluations to decide, each answered by exactly one decision with the same id. 1 to 256 items.
`evaluations[].id`	string	yes	Opaque, unique within the request. 1 to 128 characters.
`evaluations[].expression`	object	yes	The pinned Saved Query Version expression, valid against the manifest’s expression_schema.
`evaluations[].configuration`	object	yes	The pinned Subscription evaluator configuration, valid against the manifest’s configuration_schema.
`evaluations[].subscriptions`	array of object	yes	The Subscription Versions this evaluation stands for. Informational (logs, tracing): a decision must depend only on the record, the expression and the configurations.
`evaluations[].subscriptions[].subscription_id`	string	yes	—
`evaluations[].subscriptions[].subscription_version_id`	string	yes	—
`evaluations[].subscriptions[].saved_query_id`	string	yes	—
`evaluations[].subscriptions[].saved_query_version_id`	string	yes	—
`evaluations[].subscriptions[].owner`	string	no	The Subscription Owner (an opaque end-user reference of the client application); absent for a global Subscription. Informational like the ids. 1 to 128 characters.
`evaluations[].query_vector`	reserved	no	Reserved: a document that sets it is rejected.
`configuration`	object	yes	The validated plugin (installer) configuration, as for every Contribution.

Response body (200) (subscription-response.schema.json)

Field	Type	Required	Description
`decisions`	array of object	yes	At most 256 items.
`decisions[].id`	string	yes	The id of the evaluation this decision answers. 1 to 128 characters.
`decisions[].decision`	`match`, `no_match`, `not_ready`	yes	match: the Record Version satisfies the expression. no_match: it does not. not_ready: it cannot be decided yet (for example before enrichment); the core evaluates again on a later trigger. A plugin that cannot decide at all answers with the error envelope instead.
`decisions[].evidence`	object	no	Required for match, optional otherwise.
`decisions[].evidence.explanation`	string	yes	Human explanation of the decision, at most 4096 Unicode code points. 1 to 4096 characters.
`decisions[].evidence.part_keys`	array of string	no	Keys of the request Parts that support the decision; each must exist in the request. At most 100 items.
`decisions[].evidence.details`	object	no	Plugin-defined structured evidence; at most 16 KiB once serialized as JSON.

Connector

`POST /v0/contributions/connector/check_credential`

Since Plugin API 0.3. Check that the source accepts the credential, without fetching items. Used for Connector Health. Request body (connector-check-credential-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`contribution`	`"connector"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The plugin configuration the installer supplies, valid against configuration.schema.
`connector`	any	yes	—
`credential`	any	yes	—
`now`	any	yes	—

Response body (200) (connector-check-credential-response.schema.json)

Field	Type	Required	Description
`status`	`"ok"`	yes	—
`expires_at`	string	no	When the credential stops working, when the source says so; drives the credential_expiring health state.

`POST /v0/contributions/connector/describe_attachment`

Since Plugin API 0.4. The core asks for the exact size and SHA-256 of one attachment of an item it has not accepted yet, before it issues an upload grant. The plugin reads the bytes from the source, at most attachments.max_bytes, or answers a skip. Request body (connector-describe-attachment-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`contribution`	`"connector"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The plugin configuration the installer supplies, valid against configuration.schema.
`connector`	any	yes	—
`credential`	object or null	yes	The decrypted Deposited Credential, or null for a kind without one. Never log, echo or persist it.
`now`	string	yes	The core’s clock for this invocation (RFC 3339, UTC).
`item`	object	yes	The item the attachment belongs to, as the plugin returned it.
`item.record_key`	string	yes	1 to 1024 characters.
`item.revision`	string	no	1 to 256 characters.
`item.extensions`	`Extensions` (shared Manifest schema)	no	The item’s current extensions.
`attachment`	`Attachment` (shared Manifest schema)	yes	The attachment descriptor, as the plugin returned it.

Response body (200) (connector-describe-attachment-response.schema.json)

Field	Type	Required	Description
`size_bytes`	integer	no	Exact size, at most attachments.max_bytes.
`sha256`	string	no	Lowercase hex SHA-256 of the exact bytes.
`skip`	string	no	Why the attachment is left out, for example too_large when the bytes exceed attachments.max_bytes. At most 64 characters.
`item_extensions`	`Extensions` (shared Manifest schema)	no	Replaces the item’s extensions, for example to record the skipped attachment; only in namespaces the plugin declares.

`POST /v0/contributions/connector/fetch`

Since Plugin API 0.3. Fetch one page of new or changed source items after the checkpoint. The plugin is stateless between invocations: the core persists the checkpoint and advances it only after the page’s items are durably accepted. Request body (connector-fetch-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`contribution`	`"connector"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The plugin configuration the installer supplies, valid against configuration.schema.
`connector`	object	yes	The Connector Instance the core invokes the plugin for.
`connector.instance_id`	string	yes	1 to 128 characters.
`connector.kind`	string	yes	—
`connector.corpus_id`	string	no	The Corpus the instance writes to, since Plugin API 0.3.1. Relation targets bind to it: a target Source Identity is this corpus_id and source_namespace with the target’s Record Key.
`connector.source_namespace`	string	no	The Source Namespace of the instance’s Records, since Plugin API 0.3.1. 1 to 200 characters.
`connector.webhook_url`	string	no	Since Plugin API 0.5, for a kind that declares the push mode on a deployment with a public URL: the public address where the source delivers to this instance. The core relays each delivery to receive, so a plugin registers this address with the source and never needs to be reachable itself. At most 2048 characters.
`connector.config`	object	yes	The Connector Instance configuration, already valid against the kind’s config_schema.
`credential`	object or null	yes	The decrypted Deposited Credential, valid against the kind’s credential_schema; null for a kind without one, or for an instance without one when the kind’s credential_required is false. Sent only for this invocation: never log, echo or persist it.
`checkpoint`	any	yes	The opaque Acquisition Checkpoint the plugin returned last (any JSON value); null on the first run of a Connector Instance.
`now`	string	yes	The core’s clock for this invocation (RFC 3339, UTC). Use it instead of the local clock so runs are reproducible.
`page_in_run`	integer	yes	0 for the first page of a run, then counts up while the plugin answers more: true.
`reads_today`	integer	yes	Source resources read during the current UTC day, including earlier pages of this run, for sources that bill or rate-limit per resource.

Response body (200) (connector-fetch-response.schema.json)

Field	Type	Required	Description
`items`	array of object	yes	At most the declared max_items. At most 1000 items.
`items[].record_key`	string	yes	Stable source identity within the Source Namespace. 1 to 1024 characters.
`items[].revision`	string	no	Identifies the item content; absent derives it from the content. Set it when the item has attachments, so an unchanged item is recognised before anything is downloaded. 1 to 256 characters.
`items[].source_position`	string	no	Optional monotonic Source Position. 1 to 256 characters.
`items[].content`	`TextContent` (shared Manifest schema) or `ManifestContent` (shared Manifest schema)	no	Text or a Manifest. A connector Manifest carries no Blob Parts: binary Parts are attachments.
`items[].extensions`	`Extensions` (shared Manifest schema)	no	Record Version extensions, only in namespaces the plugin declares.
`items[].withdraw`	boolean	no	true asks for a Tombstone instead of a new version, for example a post deleted at the source.
`items[].attachments`	array of object	no	At most 64 items.
`items[].attachments[].key`	string	yes	1 to 256 characters.
`items[].attachments[].parent_key`	string	no	1 to 256 characters.
`items[].attachments[].role`	string	yes	1 to 64 characters.
`items[].attachments[].media_type`	string	yes	At most 255 characters.
`items[].attachments[].size_bytes`	integer	no	Announced size, when the source provides it; the exact size when sha256 is set.
`items[].attachments[].sha256`	string	no	Lowercase hex SHA-256 of the exact bytes, when the plugin already knows them; the core then skips describe_attachment.
`items[].attachments[].extensions`	`Extensions` (shared Manifest schema)	no	—
`items[].attachments[].ref`	string	yes	Opaque handle the plugin understands, given back when the core asks for the bytes. 1 to 1024 characters.
`checkpoint`	any	yes	The opaque checkpoint that resumes after this page (any JSON value, at most the declared limits.max_checkpoint_bytes serialized, 64 KiB by default). Return the request’s checkpoint unchanged when nothing moved.
`more`	boolean	yes	true asks for another page in the same run; the checkpoint must then have moved.
`reads`	integer	no	Source resources this page read; feeds the per-UTC-day usage counters. Default `0`.
`diagnostics`	object	no	Kind-defined diagnostics exposed as Connector Health diagnostics (at most 16 KiB serialized); the latest page’s value replaces the previous one.
`notice`	string	no	A condition to report on a run that completed normally, such as a spend cap; it ends the run. At most 64 characters.
`not_due`	boolean	no	true: the source asked not to be polled yet (for example an RSS ttl). The run is skipped: no items, more false and the request’s checkpoint unchanged.
`push`	object	no	Since Plugin API 0.5, for a push kind: the plugin’s view of the push channel it sets up at the source (a registered webhook and its subscriptions). active: deliveries are expected. pending: not set up yet; code may say why. failed: the source refused or broke the setup, and polling carries the collection alone; error_class access shows as the access_error Connector Health state. The core keeps the latest report.
`push.state`	`active`, `pending`, `failed`	yes	—
`push.error_class`	`access`, `transient`, `source`	no	Required when state is failed, absent otherwise.
`push.code`	string	no	Required when state is failed; an optional reason when pending; absent when active. At most 64 characters.
`push.poll_interval_seconds`	integer	no	Only with state active: while deliveries arrive, the core runs pull at most this often (the greater of this and the instance’s interval), as a safety net. It returns to the instance’s interval as soon as push degrades. 60 to 86400.

`POST /v0/contributions/connector/receive`

Since Plugin API 0.5, for a kind that declares the push mode. The core relays one request a source sent to the instance’s public webhook route: the plugin verifies it with the credential (for example a signature over the raw body), answers any challenge, and returns the items it carries. The core ingests the items, then returns the plugin’s answer to the source. Request body (connector-receive-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per delivery; correlate logs with it. 1 to 128 characters.
`contribution`	`"connector"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The plugin configuration the installer supplies, valid against configuration.schema.
`connector`	object	yes	The Connector Instance the delivery is addressed to.
`connector.instance_id`	string	yes	1 to 128 characters.
`connector.kind`	string	yes	—
`connector.corpus_id`	string	yes	The Corpus the instance writes to; Relation targets bind to it.
`connector.source_namespace`	string	yes	1 to 200 characters.
`connector.config`	object	yes	The Connector Instance configuration, already valid against the kind’s config_schema.
`credential`	object or null	yes	The decrypted Deposited Credential, for verifying the delivery. Sent only for this invocation: never log, echo or persist it.
`checkpoint`	any	yes	The current Acquisition Checkpoint, read-only: a receive answer carries no checkpoint, because pull runs own it. Null before the first run.
`now`	string	yes	The core’s clock (RFC 3339, UTC).
`reads_today`	integer	yes	Source resources read during the current UTC day, by pull runs and deliveries.
`request`	object	yes	The relayed request, bounded by the core: a body of at most 1 MiB, at most 64 header names. Hop-by-hop headers and Cookie are not relayed.
`request.method`	`GET`, `POST`	yes	—
`request.query`	string	yes	The raw query string, without the leading ?. At most 8192 characters.
`request.headers`	map of array of string	yes	Header values by lowercase name, in arrival order. At most 64 entries.
`request.body_base64`	string	yes	The exact body bytes, standard base64 (signatures cover the raw bytes); empty for no body. At most 1398104 characters.

Response body (200) (connector-receive-response.schema.json)

Field	Type	Required	Description
`verdict`	`accepted`, `refused`	yes	—
`response`	object	yes	What the core answers the source: a 2xx status for accepted, a 4xx status for refused. A challenge (such as a CRC check) is an accepted delivery with no items whose body is the challenge answer.
`response.status`	integer	yes	200 to 499.
`response.content_type`	string	no	At most 256 characters.
`response.body`	string	no	Text body returned to the source. At most 65536 characters.
`items`	array of `Item` (shared Manifest schema)	no	Items the delivery carries, at most the declared max_items. Only with verdict accepted; attachments are not supported in a delivery. At most 1000 items.
`reads`	integer	no	Source resources the delivery counts as read; feeds the per-UTC-day usage counters. Default `0`.

`POST /v0/contributions/connector/upload_attachment`

Since Plugin API 0.4. The plugin uploads the bytes it described to the grant, then answers. The core verifies the stored bytes before it accepts the item. Bytes that changed at the source since describe_attachment are a source error attachment_changed; the core describes the attachment again once. Request body (connector-upload-attachment-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`contribution`	`"connector"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The plugin configuration the installer supplies, valid against configuration.schema.
`connector`	any	yes	—
`credential`	object or null	yes	The decrypted Deposited Credential, or null for a kind without one. Never log, echo or persist it.
`now`	string	yes	The core’s clock for this invocation (RFC 3339, UTC).
`item`	object	yes	The item the attachment belongs to, as the plugin returned it.
`item.record_key`	string	yes	1 to 1024 characters.
`item.revision`	string	no	1 to 256 characters.
`item.extensions`	`Extensions` (shared Manifest schema)	no	The item’s current extensions.
`attachment`	`Attachment` (shared Manifest schema)	yes	The attachment descriptor, as the plugin returned it.
`grant`	object	yes	One presigned PUT for one storage object. Storage refuses any other length, checksum or media type. Send exactly these headers, never log the URL or the headers, and do not reuse the grant.
`grant.url`	string	yes	1 to 8192 characters.
`grant.method`	`"PUT"`	yes	—
`grant.headers`	map of string	yes	Headers the PUT must carry exactly.
`grant.size_bytes`	integer	yes	—
`grant.sha256`	string	yes	—
`grant.media_type`	string	yes	1 to 255 characters.
`grant.expires_at`	string	yes	—

Response body (200) (connector-upload-attachment-response.schema.json)

Field	Type	Required	Description
`status`	`"uploaded"`	yes	—

Ingestion

`POST /v0/contributions/ingestion/embed_query`

Since Plugin API 0.6. Encode one query into one of the plugin’s spaces, so a query vector always comes from the model that produced the document vectors. Request body (ingestion-embed-query-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`contribution`	`"ingestion"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The validated plugin (installer) configuration.
`space`	`SpaceId` (shared Manifest schema)	yes	—
`query`	object	yes	—
`query.modality`	`text`	yes	One of the space’s query_modalities. Plugin API 0.6 knows only text.
`query.text`	string	yes	The query, trimmed, with line breaks normalized to LF. 1 to 32768 characters.

Response body (200) (ingestion-embed-query-response.schema.json)

Field	Type	Required	Description
`vector`	array of number	yes	One vector, exactly as many numbers as the space’s dimensions. Values must be finite as 32-bit floats; under the cosine metric the vector must not be all zeros. 1 to 4096 items.

`POST /v0/contributions/ingestion/segment_and_embed`

Since Plugin API 0.6. One Record Version’s text Parts and the enabled vector spaces to embed each segment in. Request body (ingestion-segment-and-embed-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per attempt; correlate logs with it. 1 to 128 characters.
`idempotency_key`	string	yes	Opaque, stable across retries of the same logical invocation. The same key must yield the same segments, vectors, lexical text and provenance. 1 to 256 characters.
`contribution`	`"ingestion"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The validated plugin (installer) configuration.
`version`	object	yes	The Record Version being ingested. Informational: the answer must depend only on the Parts, the language, the spaces and the configuration.
`version.corpus_id`	string	yes	—
`version.record_id`	string	yes	—
`version.record_version_id`	string	yes	—
`language`	string	no	BCP 47 language hint, when the core knows one.
`parts`	array of object	yes	The Version’s canonical text Parts, in Manifest order, with unique keys. Blob Parts are not sent. Segment offsets address these texts. 1 to 256 items.
`parts[].key`	string	yes	—
`parts[].role`	string	yes	—
`parts[].text`	string	yes	—
`spaces`	array of `SpaceId` (shared Manifest schema)	yes	The declared spaces to embed, among those this deployment enables. Every segment carries exactly one vector for each of them. Empty (since Plugin API 0.8) asks for the segments only, without vectors: the core segments a Version first and embeds it later, and the segments must then be the same. 0 to 8 items.

Response body (200) (ingestion-segment-and-embed-response.schema.json)

Field	Type	Required	Description
`segments`	array of object	yes	1 to 1024 items.
`segments[].part_key`	string	yes	Key of the request Part the segment is cut from.
`segments[].start`	integer	yes	First Unicode code point of the segment in the Part text.
`segments[].end`	integer	yes	Code point after the last one. start = end is an empty segment, allowed only when the request has a Part with the role title: the segment then stands for the title alone.
`segments[].vectors`	map of array of number	yes	One vector per requested space, by space id; empty when the request asks for no space (since Plugin API 0.8). 0 to 8 entries.
`segments[].lexical_text`	string	no	Optional keyword-search text for the segment (for example lower-cased, folded or stemmed words). The core indexes it in a separate keyword field; excerpts always come from the source text. At most 16384 code points, no NUL.
`segments[].provenance`	object	no	Optional details of how the segment was made (token counts, the embedded text’s template), at most 4 KiB once serialized. Stored with the segmentation, never interpreted.

Retrieval

`POST /v0/contributions/retrieval/search`

Since Plugin API 0.7. One round of one search: the query, the scope, the profile, the spaces available, and every candidate the core served in earlier rounds. The plugin answers candidate requests or the final ranking. Request body (retrieval-search-request.schema.json)

Field	Type	Required	Description
`invocation_id`	string	yes	Unique per round; correlate logs with it. 1 to 128 characters.
`contribution`	`"retrieval"`	yes	—
`organization_id`	string	yes	—
`configuration`	object	yes	The validated plugin (installer) configuration.
`profile`	`ProfileName` (shared Manifest schema)	yes	One of the manifest’s profiles.
`round`	integer	yes	1 for the first call of a search; the last round the manifest allows must answer a ranking. 1 to 3.
`query`	object	yes	—
`query.text`	string	yes	1 to 8192 characters.
`query.mode`	`lexical`, `semantic`, `hybrid`	yes	The mode the client asked for; a hint the plugin may follow.
`limit`	integer	yes	Most hits the ranking may hold. 1 to 50.
`scope`	object	yes	—
`scope.corpus_ids`	array of string	yes	1 to 16 items.
`scope.source_namespaces`	array of string	no	When present, every candidate comes from one of these Source Namespaces. 1 to 50 items.
`spaces`	array of object	yes	The vector spaces near_vector and hybrid may name, the served one first. At most 16 items.
`spaces[].id`	string	yes	The space id near_vector and hybrid name (vector_space_id in the HTTP API). 1 to 200 characters.
`spaces[].owner`	object	yes	—
`spaces[].owner.kind`	`engine`, `plugin`	yes	—
`spaces[].owner.plugin_id`	`PluginId` (shared Manifest schema)	no	—
`spaces[].owner.plugin_version`	`Version` (shared Manifest schema)	no	—
`spaces[].model`	string	yes	—
`spaces[].dimensions`	integer	yes	—
`spaces[].metric`	`cosine`, `dot`, `l2`	yes	—
`spaces[].indexes`	array of string	yes	—
`spaces[].query_modalities`	array of string	yes	—
`spaces[].role`	`served`, `evaluation`	yes	served answers search by default; evaluation is indexed and compared.
`spaces[].coverage`	object	yes	—
`spaces[].coverage.segments`	integer	yes	Current segments holding a vector in this space, over every requested Corpus.
`spaces[].coverage.total`	integer	yes	Current segments of the requested Corpora.
`served`	array of object	yes	Every candidate request of earlier rounds with the candidates the core served for it, in order. Empty in round 1. At most 24 items.
`served[].round`	integer	yes	1 to 3.
`served[].request_index`	integer	yes	0 to 7.
`served[].request`	object	yes	One candidate request. bm25 ranks by keywords on a field; near_vector ranks by one space’s vectors (the core encodes query_text with the space’s owner, or takes vector as given); hybrid fuses both in one index query. Candidates are Record segments the caller may read, deduplicated by segment.
`served[].request.primitive`	`bm25`, `near_vector`, `hybrid`	yes	—
`served[].request.query_text`	string	no	The text to rank by: the search query or one the plugin rewrote. 1 to 8192 characters.
`served[].request.vector`	array of number	no	near_vector only: a query vector with the space’s dimensions, instead of query_text. 1 to 4096 items.
`served[].request.space`	string	no	near_vector and hybrid: one id of the request’s spaces. 1 to 200 characters.
`served[].request.field`	`source`, `lexical`	no	bm25 and hybrid: source ranks the title and body as written; lexical ranks the lexical text an ingestion plugin produced. Default `"source"`.
`served[].request.alpha`	number	no	hybrid: weight of the vector side (1 is vector only, 0 is keywords only). 0 to 1. Default `0.5`.
`served[].request.fusion`	`relative_score`, `ranked`	no	hybrid: how the index fuses the two sides. Default `"relative_score"`.
`served[].request.k`	integer	yes	Most candidates to serve; at most limits.max_candidates. 1 to 100.
`served[].request.filter`	object	no	Narrows the search’s scope for this request; it never widens it.
`served[].request.group_by`	`record`	no	record keeps the best candidate of each Record.
`served[].candidates`	array of object	yes	At most 100 items.
`served[].candidates[].segment_id`	string	yes	1 to 200 characters.
`served[].candidates[].record_id`	string	yes	1 to 200 characters.
`served[].candidates[].version_id`	string	yes	1 to 200 characters.
`served[].candidates[].part_key`	string	yes	1 to 200 characters.
`served[].candidates[].text`	string	yes	The segment’s text, exactly as the engine stores it.
`served[].candidates[].start`	integer	yes	Offsets of the text in its Part, in Unicode code points.
`served[].candidates[].end`	integer	yes	—
`served[].candidates[].score`	number	yes	The index score for this request; higher is better. bm25: BM25F; hybrid: the fused score; near_vector: 1 minus the distance.

Response body (200) (retrieval-search-response.schema.json)

Field	Type	Required	Description
`requests`	array of `CandidateRequest` (shared Manifest schema)	no	At most limits.max_requests; refused in the last round. 1 to 8 items.
`ranking`	object	no	—
`ranking.hits`	array of object	yes	Best first, at most the request’s limit, each segment once. At most 50 items.
`ranking.hits[].segment_id`	string	yes	A candidate the core served in this search.
`ranking.hits[].score`	number	yes	The plugin’s score; hits are in rank order.
`ranking.hits[].explanation`	string	no	Why this hit ranks here, returned to the client with it. 1 to 1024 characters.
`usage`	object	no	—
`usage.paid_calls`	integer	no	Paid calls made for this round (for example a re-ranking API).
`usage.cost_cents`	number	no	What those calls cost; a search’s total stays within the profile’s max_cost_cents.

Errors

Body of every non-2xx plugin response. retryable is authoritative: true asks the engine to retry within the declared retry intent; false is terminal. Connector errors (since Plugin API 0.3) also carry error_class, and optionally retry_after_seconds.

Field	Type	Required	Description
`code`	string	yes	At most 64 characters.
`message`	string	yes	1 to 1024 characters.
`retryable`	boolean	yes	—
`error_class`	`access`, `transient`, `source`	no	Connector error class: access (the source refuses the credential or the access; retryable false), transient (an outage or a rate limit; retryable true) or source (the source returned unusable data; retryable false). Required on connector errors: the core maps it to Connector Health.
`retry_after_seconds`	integer	no	The source accepts requests again after this delay, such as a rate-limit reset. It defers the next run and never shortens the configured interval. Only with error_class. 1 to 86400.

Fixtures

Local test inputs that quivr plugin dev and quivr plugin test turn into requests. A plugin keeps its own in fixtures/*.json.

Connector fixture

A local test input that tools turn into connector requests: quivr plugin test fetches pages from checkpoint, feeding each returned checkpoint back, checks the credential and, for a push kind, relays each receive case. A file is a connector fixture when it has a top-level connector property. Fixture credentials are test values; the Contract Runner checks they never appear in responses or plugin logs. Schema: connector-fixture.schema.json.

Field	Type	Required	Description
`description`	string	no	—
`connector`	object	yes	—
`connector.kind`	string	yes	—
`connector.config`	object	yes	—
`credential`	object or null	no	Validated against the kind’s credential_schema. Default `null`.
`configuration`	object	no	Plugin configuration; defaults to {}.
`checkpoint`	any	no	Starting checkpoint; defaults to null (a first run).
`now`	string	no	Default `"2026-01-01T00:00:00Z"`.
`max_pages`	integer	no	Most pages fetched in one run, like the core’s page bound. 1 to 50. Default `10`.
`expect`	object	no	—
`expect.pages`	array of object	no	Expected pages of the run, in order: the Record Keys of each page and optionally its more flag.
`expect.error`	object	no	The first fetch is expected to fail with this error class.
`expect.check_credential`	object	no	The expected credential check: status ok, or an error_class (and optionally its code).
`receive`	array of object	no	Since Plugin API 0.5, for a push kind: deliveries the Contract Runner relays to receive, in order, with the fixture’s config, credential and checkpoint. Signatures in headers are computed by the fixture author over the exact body. At most 32 items.
`receive[].description`	string	no	—
`receive[].request`	object	yes	—
`receive[].expect`	object	no	—

Ingestion fixture

A local test input for an ingestion plugin (since Plugin API 0.6): the text Parts of one Record Version, the queries to encode and what to expect. quivr plugin test turns it into segment_and_embed and embed_query requests. Schema: ingestion-fixture.schema.json.

Field	Type	Required	Description
`description`	string	no	—
`ingestion`	object	yes	—
`ingestion.parts`	any	yes	—
`ingestion.language`	any	no	—
`ingestion.configuration`	object	no	Plugin configuration; default {}.
`ingestion.spaces`	array of `SpaceId` (shared Manifest schema)	no	Spaces to request; default every declared space.
`ingestion.queries`	array of string	no	Queries to encode in every requested space; default the first 200 code points of the first non-empty Part. 1 to 16 items.
`ingestion.expect`	object	no	—

Normalizer fixture

A language-neutral local test input for a normalizer. Tools (quivr plugin dev, the Contract Runner, SDK test helpers) turn it into a normalizer request: they read input.path relative to the fixture file, compute its size and SHA-256, reference it through an absolute file:// URL, and fill the identity fields with deterministic development values. Schema: plugin-fixture.schema.json.

Field	Type	Required	Description
`description`	string	no	1 to 1024 characters.
`input`	object	yes	—
`input.path`	string	yes	Input file, relative to the directory of the fixture file (an absolute path is used as is). Tools resolve symbolic links before building the file:// URL.
`input.media_type`	string	yes	At most 255 characters.
`configuration`	object	no	Plugin configuration for this invocation; validated against the manifest configuration schema. Defaults to an empty object.
`source`	`SourceIdentity` (shared Manifest schema)	no	Source identity to send. Defaults to the development Corpus, namespace dev and the input path as Record Key.
`extensions`	`Extensions` (shared Manifest schema)	no	—
`provenance`	`Provenance` (shared Manifest schema)	no	—

Retrieval fixture

A local test input for a retrieval plugin (since Plugin API 0.7): a query, the spaces available and a catalogue of candidates. quivr plugin test drives the rounds and serves candidates from the catalogue, offline. Schema: retrieval-fixture.schema.json.

Field	Type	Required	Description
`description`	string	no	—
`retrieval`	object	yes	—
`retrieval.query`	string	yes	1 to 8192 characters.
`retrieval.mode`	`lexical`, `semantic`, `hybrid`	no	Default `"hybrid"`.
`retrieval.limit`	integer	no	1 to 50. Default `10`.
`retrieval.configuration`	object	no	Plugin configuration; default {}.
`retrieval.profiles`	array of `ProfileName` (shared Manifest schema)	no	Profiles to certify; default every declared profile.
`retrieval.spaces`	array of `space` (shared Manifest schema)	no	Ids of the spaces offered (served first); default one served space, fixture.served@1. At most 16 items.
`retrieval.candidates`	array of object	yes	The segments the runner may serve. Unless order says otherwise, every primitive serves them ranked by how many query words they contain, ties in catalogue order. 1 to 200 items.
`retrieval.order`	object	no	The exact segment order a primitive serves, whatever its query.
`retrieval.expect`	object	no	—

Subscription fixture

A language-neutral local test input for a subscription Contribution, since Plugin API 0.2. Tools (quivr plugin dev, the Contract Runner, SDK test helpers) turn it into a subscription request: they number the evaluations e1, e2, … in order, give each one development Subscription ids, derive the Record Version ids and the idempotency key from the SHA-256 of the fixture bytes, default the record metadata (source dev-namespace/dev-record-<digest>, origin client, accepted_at 2026-01-01T00:00:00Z) when the fixture omits it, and validate every expression and configuration against the manifest schemas. A fixture file is told apart from an invocation fixture by its top-level evaluations property. Schema: subscription-fixture.schema.json.

Field	Type	Required	Description
`description`	string	no	1 to 1024 characters.
`configuration`	object	no	Plugin (installer) configuration; validated against the manifest configuration schema. Defaults to an empty object.
`record`	object	yes	—
`record.enriched`	boolean	no	Default `false`.
`record.parts`	any	yes	—
`record.source`	any	no	—
`record.accepted_at`	any	no	—
`record.provenance`	any	no	—
`record.extensions`	any	no	—
`evaluations`	array of object	yes	1 to 256 items.
`evaluations[].description`	string	no	1 to 1024 characters.
`evaluations[].expression`	object	yes	—
`evaluations[].configuration`	object	no	Subscription evaluator configuration. Defaults to an empty object.
`evaluations[].expect`	`match`, `no_match`, `not_ready`	no	Expected decision. The Contract Runner and quivr plugin dev report a different answer.

HTTP API

Endpoints

Command line

Plugins

Deployment

Plugin protocol

Discovery and health

`GET /v0/discovery`

`GET /v0/health`

Normalizer

`POST /v0/contributions/normalizer`

Alert rule (`subscription`)

`POST /v0/contributions/subscription`

Connector

`POST /v0/contributions/connector/check_credential`

`POST /v0/contributions/connector/describe_attachment`

`POST /v0/contributions/connector/fetch`

`POST /v0/contributions/connector/receive`

`POST /v0/contributions/connector/upload_attachment`

Ingestion

`POST /v0/contributions/ingestion/embed_query`

`POST /v0/contributions/ingestion/segment_and_embed`

Retrieval

`POST /v0/contributions/retrieval/search`

Errors

Fixtures

Connector fixture

Ingestion fixture

Normalizer fixture

Retrieval fixture

Subscription fixture

​Discovery and health

​GET /v0/discovery

​GET /v0/health

​Normalizer

​POST /v0/contributions/normalizer

​Alert rule (subscription)

​POST /v0/contributions/subscription

​Connector

​POST /v0/contributions/connector/check_credential

​POST /v0/contributions/connector/describe_attachment

​POST /v0/contributions/connector/fetch

​POST /v0/contributions/connector/receive

​POST /v0/contributions/connector/upload_attachment

​Ingestion

​POST /v0/contributions/ingestion/embed_query

​POST /v0/contributions/ingestion/segment_and_embed

​Retrieval

​POST /v0/contributions/retrieval/search

​Errors

​Fixtures

​Connector fixture

​Ingestion fixture

​Normalizer fixture

​Retrieval fixture

​Subscription fixture

Discovery and health

`GET /v0/discovery`

`GET /v0/health`

Normalizer

`POST /v0/contributions/normalizer`

Alert rule (`subscription`)

`POST /v0/contributions/subscription`

Connector

`POST /v0/contributions/connector/check_credential`

`POST /v0/contributions/connector/describe_attachment`

`POST /v0/contributions/connector/fetch`

`POST /v0/contributions/connector/receive`

`POST /v0/contributions/connector/upload_attachment`

Ingestion

`POST /v0/contributions/ingestion/embed_query`

`POST /v0/contributions/ingestion/segment_and_embed`

Retrieval

`POST /v0/contributions/retrieval/search`

Errors

Fixtures

Connector fixture

Ingestion fixture

Normalizer fixture

Retrieval fixture

Subscription fixture