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.
Plugin API versions
Latest Plugin API:0.19.0. Supported versions: 0.1.0, 0.2.0, 0.3.0, 0.3.1, 0.4.0, 0.5.0, 0.6.0, 0.7.0, 0.8.0, 0.9.0, 0.10.0, 0.11.0, 0.12.0, 0.13.0, 0.14.0, 0.15.0, 0.16.0, 0.17.0, 0.18.0, 0.19.0.
Trace context
The engine sends optional W3Ctraceparent and tracestate headers on plugin
requests, plus X-Request-ID for correlation. These headers are supported with
all Plugin API versions and do not change request JSON or signing claims.
Only W3C TraceContext travels; arbitrary baggage is excluded.
Both SDK HTTP adapters extract the headers and make the current span available
to handlers through the OpenTelemetry API. They start a plugin.request span
when the plugin has configured a tracer provider; otherwise they continue the
incoming context without an exporter. SDK input-Blob HTTP reads also inject it.
Configure your plugin’s OpenTelemetry SDK and OTLP exporter in its own process
to export internal/provider spans. Do not put content, query text, credentials,
source addresses or organization identifiers in span attributes.
Go handlers receive the context as their context.Context argument; call
quivrplugin.InjectTrace(ctx, request.Header) before an outgoing provider
request. Python handlers use the current OpenTelemetry context; call
quivr_plugin.tracing.inject_headers(headers) before making an outgoing
request. Provider instrumentation must preserve that context and apply the
same privacy policy. Engine webhook deliveries use the same headers; receivers
can continue the trace after checking the webhook signature.
Signed engine requests
Plugin API0.14.0 requires Authorization: Bearer <compact JWS> on discovery
and every Contribution request. The Go and Python SDK HTTP servers verify the
token before dispatching to your handler. GET /v0/health remains public for
readiness probes. Handler code needs no change.
The engine reads QUIVR_ENGINE_PLUGIN_KEYS, a JSON object mapping plugin ids to
independent key rings. Each plugin reads only its ring from
QUIVR_PLUGIN_SIGNING_KEYS. Provision these as environment secrets, outside
manifests, plugin configuration and registry metadata. Never give a plugin the
engine’s full map. Use HTTPS for remote endpoints; tokens do not encrypt bodies.
A key ring has active (the signing key id) and keys (one to 16 keys). Each key
has id, secret (unpadded base64url of at least 32 random bytes), and optional
not_before / not_after integer Unix seconds. A key is accepted from
not_before inclusive until not_after exclusive; absent bounds are unbounded.
Ids must be unique. Generate separate secrets for each plugin. Missing or invalid
keys fail closed; signing-key diagnostics never include their values.
The JWS protected header has exactly alg: "HS256", typ: "quivr-engine+jwt"
and kid (the configured key id). All three compact segments are unpadded
base64url. Header and claims objects reject duplicate members. No other
algorithm or remote key lookup is accepted.
The eight claims above are required and no others are accepted. Verification
uses constant-time MAC comparison. Proxies must preserve method, path, query
and body bytes. Clocks must agree; no clock-skew allowance is
added. The token’s lifetime is a replay window: the same token and exact request
can be replayed until expiry. Contribution idempotency rules still apply.
A missing, malformed, forged, expired, wrong-audience, wrong-operation or
body-tampered token returns HTTP
401 with
{"code":"invalid_engine_token","message":"engine request authentication failed","retryable":false}.
A request exceeding the SDK body limit returns 413 before authentication.
For rotation, first distribute a ring containing the old and new keys to the
plugins and engine processes. Set the new key as active on engines during a
rolling restart. Keep both verification windows valid until old engine processes
are replaced and their last 60-second tokens have expired. Give the old key a
not_after cutoff for the configured overlap, then remove it. New calls continue
throughout the overlap; retired keys are refused even with an unexpired token.
A manifest restricted to an API below 0.14.0 keeps working unsigned and the
engine warns at startup. To opt in, admit 0.14.0 and upgrade the SDK, then
provision both environments. A manifest admitting the signed API cannot silently
serve an older unsigned discovery version. quivr plugin dev and quivr plugin test provision ephemeral keys when they launch the plugin; plugin test --endpoint uses QUIVR_ENGINE_PLUGIN_KEYS for that plugin.
The Contract Runner checks valid tokens and rejects missing or forged tokens,
altered identities, targets, methods, bodies, timestamps, algorithms and encodings in
fixtures/authentication/cases.json, then signs its ordinary Contribution
fixtures. Their report check id is authentication.
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)
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)
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)
Response body (200) (
normalizer-response.schema.json)
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)
Response body (200) (
subscription-response.schema.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)
Response body (200) (
connector-check-credential-response.schema.json)
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)
Response body (200) (
connector-describe-attachment-response.schema.json)
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)
Response body (200) (
connector-fetch-response.schema.json)
POST /v0/contributions/connector/receive
For a push kind. Since Plugin API 0.5 the core relays public webhook requests for the plugin to verify and answer. Since 0.11 a declared API route adds route, parsed body and request.path after engine authorization. The core ingests accepted POST items and returns Receipts for declared routes; legacy webhooks and GET challenges keep the plugin answer.
Request body (connector-receive-request.schema.json)
Response body (200) (
connector-receive-response.schema.json)
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)
Response body (200) (
connector-upload-attachment-response.schema.json)
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)
Response body (200) (
ingestion-embed-query-response.schema.json)
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)
Response body (200) (
ingestion-segment-and-embed-response.schema.json)
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)
Response body (200) (
retrieval-search-response.schema.json)
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.Fixtures
Local test inputs thatquivr plugin dev and quivr plugin test turn into requests. A plugin keeps its own in fixtures/*.json.
Authentication fixture
Normative authentication probes used by the Contract Runner. The plugin audience placeholder resolves to the tested plugin id; other audiences and the other-plugin claim placeholder resolve to a distinct id. Tokens bind GET /v0/discovery?source=engine and the exact body. Optional claim, lifetime, algorithm and JSON encoding edits are applied before signing. Unsigned omits the token; forged changes a signature byte. Schema:authentication-fixture.schema.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.
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.
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.
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.
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.