Skip to main content
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.

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 W3C traceparent 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 API 0.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 that quivr 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.