HTTP API reference

Generated from contracts/http/v0/openapi.yaml by make generate. Do not edit this page: change the source and regenerate.

Quivr V2 public text foundation contract, version 0.0.0-draft. THE-543 and THE-547 evaluation contracts; endpoint implementations are separate work. Matching criterion is plugin-owned and deferred. One configured webhook destination, immutable Matches, independent at-least-once Delivery and reference-only notifications. OpenAPI is authoritative for transport shapes. THE-640 adds text search and asynchronous Corpus projection rebuild initiation.

Authentication

Every endpoint requires ApiKey unless it says otherwise.

Scheme	Type	Description
`ApiKey`	HTTP `bearer`	API key, not necessarily a JWT. Server derives Organization, permitted actions and Corpus scope; every resource access is authorized.

Endpoints

Endpoint	Operation	Permissions
`POST /v0/records`	`ingestRecord`	`content:write`
`GET /v0/records`	`listRecords`	`content:read`
`POST /v0/records/batch`	`ingestBatch`	`content:write`
`POST /v0/records/withdrawals`	`withdrawRecord`	`content:write`
`GET /v0/records/{record_id}`	`getRecord`	`content:read`
`GET /v0/records/{record_id}/versions/{version_id}`	`getVersion`	`content:read`
`GET /v0/ingestion-receipts/{receipt_id}`	`getReceipt`	`content:read`
`POST /v0/uploads`	`createUpload`	`blobs:write`
`POST /v0/uploads/{upload_id}/confirm`	`confirmUpload`	`blobs:write`
`GET /v0/uploads/{upload_id}`	`getUpload`	`blobs:read`
`GET /v0/blobs/{blob_id}`	`getBlob`	`blobs:read`
`GET /v0/operations/{operation_id}`	`getOperation`	`operations:read`
`POST /v0/operations/{operation_id}/cancel`	`cancelOperation`	`operations:write`
`POST /v0/operations/{operation_id}/rerun`	`rerunOperation`	`operations:write`
`POST /v0/corpora`	`createCorpus`	`corpora:write`
`GET /v0/corpora`	`listCorpora`	`corpora:read`
`GET /v0/corpora/{corpus_id}`	`getCorpus`	`corpora:read`
`PUT /v0/corpora/{corpus_id}/retrieval`	`configureRetrieval`	`corpora:write`, `operations:write`
`GET /v0/corpora/{corpus_id}/vector-spaces`	`listVectorSpaces`	`corpora:read`
`POST /v0/corpora/{corpus_id}/rebuilds`	`rebuildCorpusProjection`	`projections:rebuild`
`GET /v0/changes`	`pollChanges`	`changes:read`
`GET /v0/changes/stream`	`streamChanges`	`changes:read`
`POST /v0/saved-queries`	`createSavedQuery`	`monitoring:write`
`GET /v0/saved-queries/{saved_query_id}`	`getSavedQuery`	`monitoring:read`
`GET /v0/saved-queries/{saved_query_id}/versions/{version_id}`	`getSavedQueryVersion`	`monitoring:read`
`POST /v0/saved-queries/{saved_query_id}/versions`	`createSavedQueryVersion`	`monitoring:write`
`POST /v0/saved-queries/{saved_query_id}/delete`	`deleteSavedQuery`	`monitoring:write`
`POST /v0/saved-queries/{saved_query_id}/rename`	`renameSavedQuery`	`monitoring:write`
`GET /v0/subscriptions`	`listSubscriptions`	`monitoring:read`
`POST /v0/subscriptions`	`createSubscription`	`monitoring:write`
`GET /v0/subscriptions/{subscription_id}`	`getSubscription`	`monitoring:read`
`GET /v0/subscriptions/{subscription_id}/versions/{version_id}`	`getSubscriptionVersion`	`monitoring:read`
`POST /v0/subscriptions/{subscription_id}/versions`	`createSubscriptionVersion`	`monitoring:write`
`POST /v0/subscriptions/{subscription_id}/delete`	`deleteSubscription`	`monitoring:write`
`POST /v0/subscriptions/{subscription_id}/disable`	`disableSubscription`	`monitoring:write`
`POST /v0/subscriptions/{subscription_id}/enable`	`enableSubscription`	`monitoring:write`
`POST /v0/subscriptions/{subscription_id}/rename`	`renameSubscription`	`monitoring:write`
`POST /v0/subscription-previews`	`previewSubscription`	`monitoring:write`
`GET /v0/matches`	`listMatches`	`monitoring:read`
`GET /v0/matches/{match_id}`	`getMatch`	`monitoring:read`
`GET /v0/deliveries/{delivery_id}`	`getDelivery`	`monitoring:read`
`GET /v0/deliveries/{delivery_id}/attempts`	`listDeliveryAttempts`	`monitoring:read`
`POST /v0/connectors`	`createConnector`	`connectors:write`
`GET /v0/connectors`	`listConnectors`	`connectors:read`
`GET /v0/connectors/{connector_id}`	`getConnector`	`connectors:read`
`POST /v0/connectors/{connector_id}/disable`	`disableConnector`	`connectors:write`
`PUT /v0/connectors/{connector_id}/credential`	`replaceConnectorCredential`	`connectors:write`
`PUT /v0/connectors/{connector_id}/schedule`	`changeConnectorSchedule`	`connectors:write`
`POST /v0/connectors/{connector_id}/runs`	`requestConnectorRun`	`connectors:write`
`GET /v0/connector-webhooks/{connector_id}`	`relayConnectorChallenge`
`POST /v0/connector-webhooks/{connector_id}`	`relayConnectorDelivery`
`GET /v0/connector-kinds`	`listConnectorKinds`	`connectors:read`
`GET /v0/admin/plugins`	`listPluginRegistrations`	`plugins:admin`
`GET /v0/admin/plugins/plan`	`getActivePipelinePlan`	`plugins:admin`
`POST /v0/search`	`searchRecords`	`content:read`, `search:query`
`GET /v0/search/profiles`	`listSearchProfiles`	`search:query`

Records

`POST /v0/records`

Operation ingestRecord. Requires content:write. 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. Request body (required): application/json IngestCommand Responses

Status	Body	Description
`202`	`application/json` `Receipt`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

`GET /v0/records`

Operation listRecords. Requires content:read. 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 current resources; see resynchronization procedure. The opaque page cursor is not a Change Cursor and binds the Corpus filter and authorization scope; a page cursor for another filter or scope is 409 cursor_scope_changed with resync_url. This route, relative to the API base, is the resync_url of change-feed and catalog cursor errors. Parameters

Name	In	Type	Required	Description
`corpus_id`	query	string	yes	Minimum length `1`.
`page_cursor`	query	string		Minimum length `1`.
`limit`	query	integer		Default `100`. Minimum `1`. Maximum `100`.

Responses

Status	Body	Description
`200`	`application/json` `RecordPage`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`POST /v0/records/batch`

Operation ingestBatch. Requires content:write. 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 entry_too_large), so the same entry bytes are never refused for size alone. HTTP 200 carries Receipt or Error per entry, with the same error codes as single submission. Same ingestion family/key as single submission. Reuse entry keys after unknown transport outcomes. Request body (required): application/json BatchRequest Responses

Status	Body	Description
`200`	`application/json` `BatchResult`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

`POST /v0/records/withdrawals`

Operation withdrawRecord. Requires content:write. 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. Request body (required): application/json WithdrawalCommand Responses

Status	Body	Description
`202`	`application/json` `Receipt`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

`GET /v0/records/{record_id}`

Operation getRecord. Requires content:read. Authorized canonical currentness and withdrawal view. Parameters

Name	In	Type	Required	Description
`record_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Record`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

`GET /v0/records/{record_id}/versions/{version_id}`

Operation getVersion. Requires content:read. 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. Parameters

Name	In	Type	Required	Description
`record_id`	path	string	yes	Minimum length `1`.
`version_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Version`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

Ingestion receipts

`GET /v0/ingestion-receipts/{receipt_id}`

Operation getReceipt. Requires content:read. 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. Parameters

Name	In	Type	Required	Description
`receipt_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Receipt`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

Uploads

`POST /v0/uploads`

Operation createUpload. Requires blobs:write. 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. Request body (required): application/json UploadRequest Responses

Status	Body	Description
`201`	`application/json` `Upload`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

`POST /v0/uploads/{upload_id}/confirm`

Operation confirmUpload. Requires blobs:write. Start or observe checksum/size verification; SDK polls until verified before referencing the Blob in ingestion. Confirmation is repeatable for this session. Parameters

Name	In	Type	Required	Description
`upload_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`202`	`application/json` `Upload`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

`GET /v0/uploads/{upload_id}`

Operation getUpload. Requires blobs:read. Observe upload verification independently of Ingestion Receipt. Parameters

Name	In	Type	Required	Description
`upload_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Upload`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

Blobs

`GET /v0/blobs/{blob_id}`

Operation getBlob. Requires blobs:read. Inspect verified Blob metadata within authorized Organization scope; ID possession does not grant access. Parameters

Name	In	Type	Required	Description
`blob_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Blob`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

Operations

`GET /v0/operations/{operation_id}`

Operation getOperation. Requires operations:read. Administrative progress only. This read schema does not specify every administrative command. Parameters

Name	In	Type	Required	Description
`operation_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Operation`	Successful response
`default`	`application/json` `Error`	Structured error. 400 malformed; 401 unauthenticated; 403 forbidden action; 404 absent or inaccessible; 409 conflict; 413 oversized; 422 invalid input; 429 throttled; 503 temporary failure.

`POST /v0/operations/{operation_id}/cancel`

Operation cancelOperation. Requires operations:write. 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. Parameters

Name	In	Type	Required	Description
`operation_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`202`	`application/json` `Operation`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`POST /v0/operations/{operation_id}/rerun`

Operation rerunOperation. Requires operations:write. 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. Parameters

Name	In	Type	Required	Description
`operation_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`202`	`application/json` `Operation`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

Corpora

`POST /v0/corpora`

Operation createCorpus. Requires corpora:write. Explicit Corpus creation. Same creation route-family key and canonical request replays the same Corpus. Requires corpora:write. Request body (required): application/json CorpusRequest Responses

Status	Body	Description
`201`	`application/json` `Corpus`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`GET /v0/corpora`

Operation listCorpora. Requires corpora:read. 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). Parameters

Name	In	Type	Required	Description
`page_cursor`	query	string		Minimum length `1`.
`limit`	query	integer		Default `100`. Minimum `1`. Maximum `100`.

Responses

Status	Body	Description
`200`	`application/json` `CorpusPage`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`GET /v0/corpora/{corpus_id}`

Operation getCorpus. Requires corpora:read. Read effective resolved configuration. Parameters

Name	In	Type	Required	Description
`corpus_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Corpus`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`PUT /v0/corpora/{corpus_id}/retrieval`

Operation configureRetrieval. Requires corpora:write, operations:write. 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 not its content. A newer accepted config supersedes older pending ones, and a generation pinned to an older config than the effective one fails with retrieval_configuration_superseded instead of reverting it. Same key and canonical request replay the Operation; a changed request is 409 idempotency_conflict. Does not require a separate per-Corpus physical collection. Parameters

Name	In	Type	Required	Description
`corpus_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ConfigUpdate Responses

Status	Body	Description
`202`	`application/json` `Operation`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`GET /v0/corpora/{corpus_id}/vector-spaces`

Operation listVectorSpaces. Requires corpora:read. 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 compared but never served) and its coverage, the current segments that hold a vector in it. A Corpus built before a space was enabled lists only the spaces it was built with; rebuild it (rebuildCorpusProjection) to add the others. Parameters

Name	In	Type	Required	Description
`corpus_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `VectorSpaceList`	Successful response
`default`	`application/json` `Error`	Structured error; 401 unauthenticated, 403 unauthorized scope/action, 404 absent/inaccessible, 503 dependency unavailable.

`POST /v0/corpora/{corpus_id}/rebuilds`

Operation rebuildCorpusProjection. Requires projections:rebuild. 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 same Operation, including after terminal completion; changed request conflicts. HTTP does not wait for reconstruction. Retries/restarts keep identity and target generation. Preserve other Corpora when physical storage is shared. Normal ingestion/withdrawal guards still apply. Live evaluation schema migrations remain a separate mechanism. Activation follows acceptance order, so a rebuild accepted before one that already activated for the same Corpus and retrieval configuration fails with operation_superseded instead of replacing it. Parameters

Name	In	Type	Required	Description
`corpus_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`202`	`application/json` `Operation` Header `Location`: string (uri-reference). Authorized Operation read URL.	Successful response
`default`	`application/json` `Error`	Structured error; 400 malformed, 401 unauthenticated, 403 unauthorized scope/action, 404 absent/inaccessible, 409 idempotency conflict, 422 unsupported profile/input, 503 dependency unavailable.

Changes

`GET /v0/changes`

Operation pollChanges. Requires changes:read. 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_expired with resync_url, never silent reset; changed scope/filter is 409 cursor_scope_changed with resync_url. resync_url is the API-relative Record catalog route for the Corpus (/v0/records?corpus_id=…). next_cursor advances over scanned events even when none are visible. Public events are invalidations; reread current state, do not replay historical content into a current mirror. Parameters

Name	In	Type	Required	Description
`cursor`	query	string		Minimum length `1`.
`corpus_id`	query	string	yes	Minimum length `1`.
`limit`	query	integer		Default `100`. Minimum `1`. Maximum `100`.

Responses

Status	Body	Description
`200`	`application/json` `ChangePage`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`GET /v0/changes/stream`

Operation streamChanges. Requires changes:read. 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 checkpoint. Resume cursor expires or scope changes: before headers use HTTP 410/409; after headers send stream_error with Error JSON then close, without advancing id. Use authenticated streaming fetch/http client. See contract for checkpoint framing and resync. Parameters

Name	In	Type	Required	Description
`cursor`	query	string		Minimum length `1`.
`corpus_id`	query	string	yes	Minimum length `1`.
`Last-Event-ID`	header	string		Minimum length `1`.

Responses

Status	Body	Description
`200`	`text/event-stream` string	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

Example 200 response text/event-stream:

id: opaque-cursor
event: change
data: {"event_id":"event_1","type":"record.searchable","schema_version":"1","occurred_at":"2026-09-14T12:00:00Z","resource":{"kind":"record","id":"record_1","corpus_id":"corpus_1"},"cursor":"opaque-cursor"}

Saved queries

`POST /v0/saved-queries`

Operation createSavedQuery. Requires monitoring:write. Persist definition and first immutable version. Replay same key/request returns same IDs; conflict on changed request. Query creation alone evaluates nothing. Request body (required): application/json SavedQueryCreate Responses

Status	Body	Description
`201`	`application/json` `SavedQuery`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`GET /v0/saved-queries/{saved_query_id}`

Operation getSavedQuery. Requires monitoring:read. Authorized current query view. Parameters

Name	In	Type	Required	Description
`saved_query_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `SavedQuery`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`GET /v0/saved-queries/{saved_query_id}/versions/{version_id}`

Operation getSavedQueryVersion. Requires monitoring:read. 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. Parameters

Name	In	Type	Required	Description
`saved_query_id`	path	string	yes	Minimum length `1`.
`version_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `SavedQueryVersion`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/saved-queries/{saved_query_id}/versions`

Operation createSavedQueryVersion. Requires monitoring:write. 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 definitions. Replay of the same key and request returns the same Version; a changed request is 409 idempotency_conflict. A deleted Saved Query is 409 saved_query_deleted. Parameters

Name	In	Type	Required	Description
`saved_query_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json SavedQueryVersionCreate Responses

Status	Body	Description
`201`	`application/json` `SavedQueryVersion`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/saved-queries/{saved_query_id}/delete`

Operation deleteSavedQuery. Requires monitoring:write. 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. Parameters

Name	In	Type	Required	Description
`saved_query_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`200`	`application/json` `SavedQuery`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/saved-queries/{saved_query_id}/rename`

Operation renameSavedQuery. Requires monitoring:write. 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 request returns the Saved Query; a changed request is 409 idempotency_conflict. A deleted Saved Query is 409 saved_query_deleted. Parameters

Name	In	Type	Required	Description
`saved_query_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json RenameRequest Responses

Status	Body	Description
`200`	`application/json` `SavedQuery`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

Subscriptions

`GET /v0/subscriptions`

Operation listSubscriptions. Requires monitoring:read. 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. Quivr applies no per-owner rule; a layer above can use this listing to enforce its own. Parameters

Name	In	Type	Required	Description
`owner`	query	string	yes	A Subscription Owner, or none for global Subscriptions. Minimum length `1`. Maximum length `128`.
`page_cursor`	query	string		Minimum length `1`.
`limit`	query	integer		Default `100`. Minimum `1`. Maximum `100`.

Responses

Status	Body	Description
`200`	`application/json` `SubscriptionPage`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/subscriptions`

Operation createSubscription. Requires monitoring:write. 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 unsupported_evaluator); the pinned Saved Query Version expression and the evaluator configuration must satisfy the evaluator’s declared schemas (422 invalid_expression with field /saved_query_version_id, or invalid_subscription_configuration with field /evaluator/configuration/…; message names the first schema issue). Request body (required): application/json SubscriptionCreate Responses

Status	Body	Description
`201`	`application/json` `Subscription`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`GET /v0/subscriptions/{subscription_id}`

Operation getSubscription. Requires monitoring:read. Read enabled state and pinned current configuration. Parameters

Name	In	Type	Required	Description
`subscription_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Subscription`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`GET /v0/subscriptions/{subscription_id}/versions/{version_id}`

Operation getSubscriptionVersion. Requires monitoring:read. 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. Parameters

Name	In	Type	Required	Description
`subscription_id`	path	string	yes	Minimum length `1`.
`version_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `SubscriptionVersion`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/subscriptions/{subscription_id}/versions`

Operation createSubscriptionVersion. Requires monitoring:write. 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 subscription.updated in every Corpus of the previous and new scope. Each later change is judged by the new Version, each earlier one by the Version effective before it. Nothing is backfilled and Matches keep the Version that produced them. Enabled state is unchanged. The evaluator, expression and configuration are checked as on creation (422 unsupported_evaluator, invalid_expression or invalid_subscription_configuration). Replay of the same key and request returns the same Version; a changed request is 409 idempotency_conflict. A deleted Subscription is 409 subscription_deleted. Parameters

Name	In	Type	Required	Description
`subscription_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json SubscriptionVersionCreate Responses

Status	Body	Description
`201`	`application/json` `SubscriptionVersion`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/subscriptions/{subscription_id}/delete`

Operation deleteSubscription. Requires monitoring:write. 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.withdrawn notice for one of its Matches is still committed with its pending Delivery, which is never attempted. The Subscription, its Versions, Matches and Deliveries stay readable with deleted true. Enable or edit is then 409 subscription_deleted. Repeat is idempotent and commits no event. Parameters

Name	In	Type	Required	Description
`subscription_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`200`	`application/json` `Subscription`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/subscriptions/{subscription_id}/disable`

Operation disableSubscription. Requires monitoring:write. 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-enable. Repeat is idempotent; history remains. Parameters

Name	In	Type	Required	Description
`subscription_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`200`	`application/json` `Subscription`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/subscriptions/{subscription_id}/enable`

Operation enableSubscription. Requires monitoring:write. 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 match.withdrawn notice committed while disabled, whose window starts at this re-enable. Enabling an enabled Subscription, or repeating the request, is idempotent and commits no event. A deleted Subscription is 409 subscription_deleted. Parameters

Name	In	Type	Required	Description
`subscription_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`200`	`application/json` `Subscription`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`POST /v0/subscriptions/{subscription_id}/rename`

Operation renameSubscription. Requires monitoring:write. 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 Version; the same name commits nothing. Replay of the same key and request returns the Subscription; a changed request is 409 idempotency_conflict. A deleted Subscription is 409 subscription_deleted. Parameters

Name	In	Type	Required	Description
`subscription_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json RenameRequest Responses

Status	Body	Description
`200`	`application/json` `Subscription`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

Subscription previews

`POST /v0/subscription-previews`

Operation previewSubscription. Requires monitoring:write. 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 idempotent. The Saved Query is an inline definition or an existing Saved Query Version; the pair is validated as at Subscription creation (422 unsupported_evaluator, invalid_expression, invalid_subscription_configuration). Each Record Version costs one evaluator call, sent with the synthetic Subscription reference preview. At most limit Record Versions (1 to 50, default 20) are judged, within a time budget of a few seconds; those still undecided when it runs out are left out and complete is false. An evaluator that cannot be reached or reports a transient failure fails the preview with 503 evaluator_unavailable, and one that refuses or breaks an evaluation with 502 evaluator_error. Quivr applies no rate or cost rule; a layer above can limit who previews and how often. Request body (required): application/json SubscriptionPreviewRequest Responses

Status	Body	Description
`200`	`application/json` `SubscriptionPreview`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication and scope semantics apply.

Matches

`GET /v0/matches`

Operation listMatches. Requires monitoring:read. 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. Parameters

Name	In	Type	Required	Description
`subscription_id`	query	string	yes	Minimum length `1`.
`page_cursor`	query	string		Minimum length `1`.
`limit`	query	integer		Default `100`. Minimum `1`. Maximum `100`.

Responses

Status	Body	Description
`200`	`application/json` `MatchPage`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`GET /v0/matches/{match_id}`

Operation getMatch. Requires monitoring:read. 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. Parameters

Name	In	Type	Required	Description
`match_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Match`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

Deliveries

`GET /v0/deliveries/{delivery_id}`

Operation getDelivery. Requires monitoring:read. Read logical notification status and current admission view. Rights on the referenced Subscription/Corpus are still required for withdrawal-notice metadata. Parameters

Name	In	Type	Required	Description
`delivery_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Delivery`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

`GET /v0/deliveries/{delivery_id}/attempts`

Operation listDeliveryAttempts. Requires monitoring:read. Paginated append-only transport history, without secrets or receiver bodies. Parameters

Name	In	Type	Required	Description
`delivery_id`	path	string	yes	Minimum length `1`.
`page_cursor`	query	string		Minimum length `1`.
`limit`	query	integer		Default `100`. Minimum `1`. Maximum `100`.

Responses

Status	Body	Description
`200`	`application/json` `DeliveryAttemptPage`	Successful response
`default`	`application/json` `Error`	Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

Connectors

`POST /v0/connectors`

Operation createConnector. Requires connectors:write. 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 member. Replaying the same idempotency key and request returns the same instance (without re-enabling a disabled one); a different request under the same key is 409 idempotency_conflict. Another enabled instance on the same Corpus and Source Namespace is 409 source_namespace_in_use. The interval defaults per kind and is refused below the deployment floor (30 s by default) with 422 invalid_interval. Deposited credentials are write-only and never returned. A deployment without a credential key refuses any request carrying a credential with 503 credentials_unavailable (retryable false) before storing or digesting it; instances without a credential are unaffected. Commits connector.created in the change feed. Request body (required): application/json ConnectorCreate Responses

Status	Body	Description
`201`	`application/json` `Connector`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`GET /v0/connectors`

Operation listConnectors. Requires connectors:read. 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). Parameters

Name	In	Type	Description
`corpus_id`	query	string	Minimum length `1`.
`page_cursor`	query	string	Minimum length `1`.
`limit`	query	integer	Default `100`. Minimum `1`. Maximum `100`.

Responses

Status	Body	Description
`200`	`application/json` `ConnectorPage`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`GET /v0/connectors/{connector_id}`

Operation getConnector. Requires connectors:read. Read configuration, credential metadata (never the secret) and the last evaluated Connector Health. Instances of other Organizations or unauthorized Corpora are 404. Parameters

Name	In	Type	Required	Description
`connector_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`200`	`application/json` `Connector`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`POST /v0/connectors/{connector_id}/disable`

Operation disableConnector. Requires connectors:write. 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. Parameters

Name	In	Type	Required	Description
`connector_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`200`	`application/json` `Connector`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`PUT /v0/connectors/{connector_id}/credential`

Operation replaceConnectorCredential. Requires connectors:write. 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.credential_replaced, and connector.health_changed when the evaluated health changes. A deployment without a credential key refuses every rotation with 503 credentials_unavailable (retryable false) before storing or digesting it. Parameters

Name	In	Type	Required	Description
`connector_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json CredentialReplace Responses

Status	Body	Description
`200`	`application/json` `Connector`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`PUT /v0/connectors/{connector_id}/schedule`

Operation changeConnectorSchedule. Requires connectors:write. 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 the deployment floor (30 s by default) or above 24 h is 422 invalid_interval with field /interval_seconds. Commits connector.schedule_changed only when the interval changes. Parameters

Name	In	Type	Required	Description
`connector_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ScheduleChange Responses

Status	Body	Description
`200`	`application/json` `Connector`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

`POST /v0/connectors/{connector_id}/runs`

Operation requestConnectorRun. Requires connectors:write. 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 the deployment interval floor (30 s by default) after the previous run ended, nor before the Retry-After the source asked for. The run then goes through the usual scheduler lease and records its outcome in health, committing connector.health_changed when the state changes; the request itself commits no event. run_at is when the run is due; the scheduler starts it within seconds after. A disabled instance is 409 connector_disabled. Parameters

Name	In	Type	Required	Description
`connector_id`	path	string	yes	Minimum length `1`.

Request body (required): application/json ActionRequest Responses

Status	Body	Description
`202`	`application/json` `ConnectorRunRequest`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

Connector webhooks

`GET /v0/connector-webhooks/{connector_id}`

Operation relayConnectorChallenge. No authentication. 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 the plugin like a delivery. Parameters

Name	In	Type	Required	Description
`connector_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`2XX`		The connector plugin accepted the delivery; its items were ingested before this answer. The body and content type are the plugin’s answer to the source (for example a challenge response).
`4XX`		The connector plugin refused the delivery (for example a bad signature), with its own body; nothing changed. 404 names no enabled instance of a kind that declares push; 413 a body over 1 MiB.
`500`		The delivery cannot be processed (the plugin reported an access or source error), shown in health.push.
`503`		Temporarily unavailable (the plugin is unreachable or ingestion is down); retry after Retry-After seconds. Polling catches up meanwhile.

`POST /v0/connector-webhooks/{connector_id}`

Operation relayConnectorDelivery. No authentication. 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 health.push. Parameters

Name	In	Type	Required	Description
`connector_id`	path	string	yes	Minimum length `1`.

Responses

Status	Body	Description
`2XX`		The connector plugin accepted the delivery; its items were ingested before this answer. The body and content type are the plugin’s answer to the source (for example a challenge response).
`4XX`		The connector plugin refused the delivery (for example a bad signature), with its own body; nothing changed. 404 names no enabled instance of a kind that declares push; 413 a body over 1 MiB.
`500`		The delivery cannot be processed (the plugin reported an access or source error), shown in health.push.
`503`		Temporarily unavailable (the plugin is unreachable or ingestion is down); retry after Retry-After seconds. Polling catches up meanwhile.

Connector kinds

`GET /v0/connector-kinds`

Operation listConnectorKinds. Requires connectors:read. 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 create carrying a credential and every rotation is 503 credentials_unavailable. Responses

Status	Body	Description
`200`	`application/json` `ConnectorKindCatalog`	Successful response
`default`	`application/json` `Error`	Structured error; see contract HTTP mapping.

Admin

`GET /v0/admin/plugins`

Operation listPluginRegistrations. Requires plugins:admin. 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 pinned in the startup configuration. Deployment-wide and not paginated. Requires plugins:admin, an operator action that organization keys do not get. Responses

Status	Body	Description
`200`	`application/json` `PluginRegistrationList`	Successful response
`default`	`application/json` `Error`	Structured error; 401 unauthenticated, 403 without plugins:admin, 503 storage unavailable.

`GET /v0/admin/plugins/plan`

Operation getActivePipelinePlan. Requires plugins:admin. 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. Responses

Status	Body	Description
`200`	`application/json` `PipelinePlan`	Successful response
`default`	`application/json` `Error`	Structured error; 401 unauthenticated, 403 without plugins:admin, 404 no active plan, 503 storage unavailable.

Search

`POST /v0/search`

Operation searchRecords. Requires content:read, search:query. 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. Profile selection does not change access/currentness rules. When a retrieval plugin is pinned, it ranks. It asks the engine for candidates in up to three rounds and returns its ranking, which may hold only candidates the engine served in this search, each already authorized and hydrated. Request body (required): application/json SearchRequest Responses

Status	Body	Description
`200`	`application/json` `SearchResponse`	Successful response
`default`	`application/json` `Error`	Structured error; 400 malformed, 401 unauthenticated, 403 unauthorized scope/action, 404 absent/inaccessible, 409 idempotency conflict, 422 unsupported_profile, query_too_long (the query is over the profile’s or the vector space owner’s length limit; the message names it), unsupported_search or source_filter_unavailable, 502 retrieval_plugin_invalid (the retrieval plugin broke its contract, for example ranked a segment the engine never served it), 503 dependency unavailable, 504 search_deadline_exceeded (the search outran its profile’s max_latency_ms).

`GET /v0/search/profiles`

Operation listSearchProfiles. Requires search:query. The search profiles this deployment answers, default first. Without a retrieval plugin only the built-in default exists; with one, its declared profiles and budgets. Responses

Status	Body	Description
`200`	`application/json` `SearchProfileList`	Successful response
`default`	`application/json` `Error`	Structured error; 401 unauthenticated, 403 unauthorized scope/action.

Webhooks

Requests the server sends to a receiver you run; they are not routes of this API.

`monitoringNotification` (POST)

Operation receiveMonitoringNotification. No authentication. 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. Parameters

Name	In	Type	Required	Description
`webhook-id`	header	string	yes	Minimum length `1`.
`webhook-timestamp`	header	string	yes	Minimum length `1`.
`webhook-signature`	header	string	yes	Minimum length `1`.

Request body (required): application/json WebhookEvent Responses

Status	Body	Description
`2XX`		Receiver durably accepted/deduplicated this event.
`default`		Transport retry policy applies; do not create another Match.

Schemas

`SourceIdentity`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share.

Field	Type	Required	Description
`corpus_id`	string	yes	Minimum length `1`.
`namespace`	string	yes	Minimum length `1`.
`record_key`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  corpus_id:
    type: string
    minLength: 1
  namespace:
    type: string
    minLength: 1
  record_key:
    type: string
    minLength: 1
required:
  - corpus_id
  - namespace
  - record_key

`Error`

Field	Type	Required	Description
`code`	string	yes	Minimum length `1`.
`message`	string	yes	Minimum length `1`.
`retryable`	boolean	yes
`field`	string		JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for example /config/url or /credential/secret/token on connector commands). Minimum length `1`.
`resync_url`	string (uri-reference)

Full schema

type: object
additionalProperties: false
properties:
  code:
    type: string
    minLength: 1
  message:
    type: string
    minLength: 1
  retryable:
    type: boolean
  field:
    type: string
    minLength: 1
    description: JSON Pointer (RFC 6901) to the request member that caused a 422, when known (for example /config/url or /credential/secret/token on connector commands).
  resync_url:
    type: string
    format: uri-reference
required:
  - code
  - message
  - retryable

`Diagnostic`

A structured processing diagnostic. plugin, contribution and invocation_id name the external invocation a normalization diagnostic concerns. Codes of external normalization:

normalizer_failed: the normalizer answered a terminal error. The Version is quarantined.
normalizer_invalid_output: the output broke the Plugin Protocol or the Manifest rules (schema, malformed or duplicate Part, a Blob Part that is not the input Blob or has another checksum, an undeclared extension namespace, too many Parts, a response over the size bound). Nothing from it is published; the Version is quarantined.
normalizer_timeout: the invocations kept exceeding the timeout until the retry budget (the manifest’s retry.max_attempts, capped by the engine at 5) was spent. The Version is quarantined.
normalizer_retries_exhausted: the normalizer kept answering retryable errors until the retry budget was spent. The Version is quarantined.
input_unverified: the input Blob was no longer the verified accepted input. The Version is quarantined.
normalizer_unrouted: the media type’s route was removed after acceptance and the built-in text path cannot read it (a text/* Blob takes the built-in text path instead). The Version is quarantined.
normalization_superseded: a newer revision of the Record was accepted before this Version was normalized, so the normalizer was not invoked. The Version is quarantined and never current.
normalizer_conflict: a later invocation with the same idempotency key returned a different output. The first recorded output is kept and published; nothing is overwritten.

On an optional route every quarantining code above that comes from the normalizer is instead listed on a searchable Version published through the built-in text path. A plugin that is unavailable (connection failure, 5xx without an error envelope, discovery that does not match the pinned manifest) is retried with backoff and never produces a diagnostic here; the Receipt shows plugin_unavailable while it retries. Quarantined Versions keep their input reference and reason; reprocessing them is not available yet.

Field	Type	Required	Description
`code`	string	yes	Minimum length `1`.
`message`	string	yes	Minimum length `1`.
`retryable`	boolean	yes	Whether the same input may succeed if processed again.
`plugin`	string		Plugin id of the invocation. Minimum length `1`.
`contribution`	string		Minimum length `1`.
`invocation_id`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
description: |-
  A structured processing diagnostic. plugin, contribution and invocation_id name the external
  invocation a normalization diagnostic concerns. Codes of external normalization:

  - normalizer_failed: the normalizer answered a terminal error. The Version is quarantined.
  - normalizer_invalid_output: the output broke the Plugin Protocol or the Manifest rules (schema,
    malformed or duplicate Part, a Blob Part that is not the input Blob or has another checksum,
    an undeclared extension namespace, too many Parts, a response over the size bound). Nothing
    from it is published; the Version is quarantined.
  - normalizer_timeout: the invocations kept exceeding the timeout until the retry budget (the
    manifest's retry.max_attempts, capped by the engine at 5) was spent. The Version is quarantined.
  - normalizer_retries_exhausted: the normalizer kept answering retryable errors until the retry
    budget was spent. The Version is quarantined.
  - input_unverified: the input Blob was no longer the verified accepted input. The Version is
    quarantined.
  - normalizer_unrouted: the media type's route was removed after acceptance and the built-in text
    path cannot read it (a text/* Blob takes the built-in text path instead). The Version is
    quarantined.
  - normalization_superseded: a newer revision of the Record was accepted before this Version was
    normalized, so the normalizer was not invoked. The Version is quarantined and never current.
  - normalizer_conflict: a later invocation with the same idempotency key returned a different
    output. The first recorded output is kept and published; nothing is overwritten.

  On an optional route every quarantining code above that comes from the normalizer is instead
  listed on a searchable Version published through the built-in text path. A plugin that is
  unavailable (connection failure, 5xx without an error envelope, discovery that does not match the
  pinned manifest) is retried with backoff and never produces a diagnostic here; the Receipt shows
  plugin_unavailable while it retries. Quarantined Versions keep their input reference and reason;
  reprocessing them is not available yet.
properties:
  code:
    type: string
    minLength: 1
  message:
    type: string
    minLength: 1
  retryable:
    type: boolean
    description: Whether the same input may succeed if processed again.
  plugin:
    type: string
    minLength: 1
    description: Plugin id of the invocation.
  contribution:
    type: string
    minLength: 1
  invocation_id:
    type: string
    minLength: 1
required:
  - code
  - message
  - retryable

`Extensions`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share. Keys are plugin namespaces. Data is validated against the installed schema version; source data is not a computed Annotation. Type: map of object.

Field	Type	Required	Description
`*.schema_version`	string	yes	Minimum length `1`.
`*.data`	object	yes

Full schema

type: object
additionalProperties:
  type: object
  additionalProperties: false
  properties:
    schema_version:
      type: string
      minLength: 1
    data:
      type: object
      additionalProperties: true
  required:
    - schema_version
    - data
description: Keys are plugin namespaces. Data is validated against the installed schema version; source data is not a computed Annotation.

`TextContent`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share.

Field	Type	Required	Description
`kind`	string	yes	One of `text`.
`text`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  kind:
    type: string
    enum:
      - text
  text:
    type: string
    minLength: 1
required:
  - kind
  - text

`BlobContent`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share.

Field	Type	Required	Description
`kind`	string	yes	One of `blob`.
`blob_id`	string	yes	Minimum length `1`.
`media_type`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  kind:
    type: string
    enum:
      - blob
  blob_id:
    type: string
    minLength: 1
  media_type:
    type: string
    minLength: 1
required:
  - kind
  - blob_id
  - media_type

`Part`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share.

Field	Type	Required	Description
`key`	string	yes	Minimum length `1`.
`parent_key`	string		Minimum length `1`.
`role`	string	yes	Minimum length `1`.
`content`	one of `TextContent`, `BlobContent`	yes
`extensions`	`Extensions`

Full schema

type: object
additionalProperties: false
properties:
  key:
    type: string
    minLength: 1
  parent_key:
    type: string
    minLength: 1
  role:
    type: string
    minLength: 1
  content:
    oneOf:
      - $ref: '#/components/schemas/TextContent'
      - $ref: '#/components/schemas/BlobContent'
  extensions:
    $ref: '#/components/schemas/Extensions'
required:
  - key
  - role
  - content

`RelationInput`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share. Source-provided link to an independently identified Record in the same Organization. Optional source revision preserves provenance; ordinary expansion resolves the current eligible target. Missing targets do not block readiness. Every expansion reauthorizes the target. Precise Part-target syntax remains outside this initial draft.

Field	Type	Required	Description
`type`	string	yes	Minimum length `1`.
`target`	`SourceIdentity`	yes
`source_target_revision`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  type:
    type: string
    minLength: 1
  target:
    $ref: '#/components/schemas/SourceIdentity'
  source_target_revision:
    type: string
    minLength: 1
required:
  - type
  - target
description: Source-provided link to an independently identified Record in the same Organization. Optional source revision preserves provenance; ordinary expansion resolves the current eligible target. Missing targets do not block readiness. Every expansion reauthorizes the target. Precise Part-target syntax remains outside this initial draft.

`ManifestContent`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share. Unique Part keys, acyclic parent references within this Manifest, and verified same-Organization Blobs are checked before atomic publication. These semantic constraints need server validation in addition to JSON Schema.

Field	Type	Required	Description
`kind`	string	yes	One of `manifest`.
`parts`	array of `Part`	yes	At least `1` items.
`relations`	array of `RelationInput`

Full schema

type: object
additionalProperties: false
properties:
  kind:
    type: string
    enum:
      - manifest
  parts:
    type: array
    items:
      $ref: '#/components/schemas/Part'
    minItems: 1
  relations:
    type: array
    items:
      $ref: '#/components/schemas/RelationInput'
required:
  - kind
  - parts
description: Unique Part keys, acyclic parent references within this Manifest, and verified same-Organization Blobs are checked before atomic publication. These semantic constraints need server validation in addition to JSON Schema.

`Provenance`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share.

Field	Type	Description
`source_blob_ids`	array of string	Each item: Minimum length `1`.
`producer`	string	Minimum length `1`.
`producer_version`	string	Minimum length `1`.
`normalization`	`NormalizationProvenance`

Full schema

type: object
additionalProperties: false
properties:
  source_blob_ids:
    type: array
    items:
      type: string
      minLength: 1
  producer:
    type: string
    minLength: 1
  producer_version:
    type: string
    minLength: 1
  normalization:
    $ref: '#/components/schemas/NormalizationProvenance'
required: []

`NormalizationProvenance`

Defined in contracts/shared/v0/manifest.schema.json, which other contracts share. Engine-owned record of the external normalizer invocation whose output a Record Version publishes. Present only on read; a submission that sets it is rejected. producer and producer_version keep naming the acquirer, and source_blob_ids keeps the input Blob.

Field	Type	Required	Description
`plugin_id`	string	yes	Minimum length `1`. Maximum length `64`.
`plugin_version`	string	yes	Minimum length `1`. Maximum length `64`.
`plugin_api`	string	yes	Plugin API version the engine invoked. Minimum length `1`. Maximum length `32`.
`contribution`	string	yes	One of `normalizer`.
`invocation_id`	string	yes	Minimum length `1`. Maximum length `128`.
`idempotency_key`	string	yes	Minimum length `1`. Maximum length `256`.
`input_sha256`	string	yes	Pattern `^[0-9a-f]{64}$`.
`fallback`	object		Present when the route is optional and the normalizer failed: the published Manifest comes from the built-in text path, and invocation_id names the failed invocation.
`fallback.code`	string	yes	Minimum length `1`. Maximum length `64`.
`fallback.message`	string	yes	Minimum length `1`. Maximum length `1000`.

Full schema

type: object
additionalProperties: false
description: Engine-owned record of the external normalizer invocation whose output a Record Version publishes. Present only on read; a submission that sets it is rejected. producer and producer_version keep naming the acquirer, and source_blob_ids keeps the input Blob.
properties:
  plugin_id:
    type: string
    minLength: 1
    maxLength: 64
  plugin_version:
    type: string
    minLength: 1
    maxLength: 64
  plugin_api:
    type: string
    minLength: 1
    maxLength: 32
    description: Plugin API version the engine invoked.
  contribution:
    type: string
    enum:
      - normalizer
  invocation_id:
    type: string
    minLength: 1
    maxLength: 128
  idempotency_key:
    type: string
    minLength: 1
    maxLength: 256
  input_sha256:
    type: string
    pattern: ^[0-9a-f]{64}$
  fallback:
    type: object
    additionalProperties: false
    description: 'Present when the route is optional and the normalizer failed: the published Manifest comes from the built-in text path, and invocation_id names the failed invocation.'
    properties:
      code:
        type: string
        minLength: 1
        maxLength: 64
      message:
        type: string
        minLength: 1
        maxLength: 1000
    required:
      - code
      - message
required:
  - plugin_id
  - plugin_version
  - plugin_api
  - contribution
  - invocation_id
  - idempotency_key
  - input_sha256

`IngestCommand`

Initial request shape. Same source identity creates or corrects a Record. Same external revision with different canonical content conflicts. No revision means canonical Manifest digest identity; no source position means durable acceptance order. Single and batch entry replay share route_family=ingestion. A blob content accepts a verified text/* Blob, read at acceptance, or a Blob whose media type the installation routes to an external normalizer; that normalizer runs after acceptance and its output is the published Manifest, while the Version identity still derives from the submitted Blob. When the normalizer fails, the Version is quarantined with a Diagnostic on the Version read (or, on an optional text/* route, published through the built-in text path with provenance.normalization.fallback). Other media types are rejected with unverified_blob. provenance.normalization is engine-owned and rejected on input. Extension namespaces owned by the pinned plugin are written only by its normalizer output, published on the Version; a submission writing one, top-level or on a Part, is rejected with 422 extension_namespace_owned.

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`source`	`SourceIdentity`	yes
`source_revision`	string		Minimum length `1`.
`source_position`	string		Optional monotonic source position, encoded as decimal text to avoid JSON numeric precision loss. Pattern `^[0-9]+$`.
`content`	one of `TextContent`, `BlobContent`, `ManifestContent`	yes
`extensions`	`Extensions`
`provenance`	`Provenance`

Example structured_inline:

{
  "idempotency_key": "import-42:item-7",
  "source": {
    "corpus_id": "corpus_news",
    "namespace": "example-feed",
    "record_key": "article-123"
  },
  "source_revision": "2",
  "content": {
    "kind": "text",
    "text": "Le texte de la dépêche…"
  },
  "extensions": {
    "example.editorial": {
      "schema_version": "1",
      "data": {
        "headline": "Titre échantillon",
        "subjects": [
          {
            "code": "science",
            "score": 0.75
          }
        ],
        "flags": {
          "urgent": true
        },
        "extra": null
      }
    }
  }
}

Example structured_manifest:

{
  "idempotency_key": "import-42:item-7",
  "source": {
    "corpus_id": "corpus_news",
    "namespace": "example-feed",
    "record_key": "article-123"
  },
  "source_revision": "2",
  "content": {
    "kind": "manifest",
    "parts": [
      {
        "key": "body",
        "role": "body",
        "content": {
          "kind": "text",
          "text": "Texte"
        },
        "extensions": {
          "example.editorial": {
            "schema_version": "1",
            "data": {
              "headline": "Titre échantillon",
              "subjects": [
                {
                  "code": "science",
                  "score": 0.75
                }
              ],
              "flags": {
                "urgent": true
              },
              "extra": null
            }
          }
        }
      },
      {
        "key": "source",
        "role": "source",
        "content": {
          "kind": "blob",
          "blob_id": "blob_original",
          "media_type": "application/xml"
        }
      }
    ],
    "relations": [
      {
        "type": "illustrated_by",
        "target": {
          "corpus_id": "corpus_news",
          "namespace": "example-feed",
          "record_key": "photo-8"
        },
        "source_target_revision": "1"
      }
    ]
  },
  "extensions": {
    "example.editorial": {
      "schema_version": "1",
      "data": {
        "headline": "Titre échantillon",
        "subjects": [
          {
            "code": "science",
            "score": 0.75
          }
        ],
        "flags": {
          "urgent": true
        },
        "extra": null
      }
    }
  },
  "provenance": {
    "source_blob_ids": [
      "blob_original"
    ],
    "producer": "example.plugin",
    "producer_version": "sha256:pinned"
  }
}

Example blob_input:

{
  "idempotency_key": "import-42:item-7",
  "source": {
    "corpus_id": "corpus_news",
    "namespace": "example-feed",
    "record_key": "article-123"
  },
  "source_revision": "2",
  "content": {
    "kind": "blob",
    "blob_id": "blob_text",
    "media_type": "text/plain"
  },
  "extensions": {
    "example.editorial": {
      "schema_version": "1",
      "data": {
        "headline": "Titre échantillon",
        "subjects": [
          {
            "code": "science",
            "score": 0.75
          }
        ],
        "flags": {
          "urgent": true
        },
        "extra": null
      }
    }
  }
}

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  source:
    $ref: '#/components/schemas/SourceIdentity'
  source_revision:
    type: string
    minLength: 1
  source_position:
    type: string
    pattern: ^[0-9]+$
    description: Optional monotonic source position, encoded as decimal text to avoid JSON numeric precision loss.
  content:
    oneOf:
      - $ref: '#/components/schemas/TextContent'
      - $ref: '#/components/schemas/BlobContent'
      - $ref: '#/components/schemas/ManifestContent'
    discriminator:
      propertyName: kind
      mapping:
        text: '#/components/schemas/TextContent'
        blob: '#/components/schemas/BlobContent'
        manifest: '#/components/schemas/ManifestContent'
  extensions:
    $ref: '#/components/schemas/Extensions'
  provenance:
    $ref: '#/components/schemas/Provenance'
required:
  - idempotency_key
  - source
  - content
description: Initial request shape. Same source identity creates or corrects a Record. Same external revision with different canonical content conflicts. No revision means canonical Manifest digest identity; no source position means durable acceptance order. Single and batch entry replay share route_family=ingestion. A blob content accepts a verified text/* Blob, read at acceptance, or a Blob whose media type the installation routes to an external normalizer; that normalizer runs after acceptance and its output is the published Manifest, while the Version identity still derives from the submitted Blob. When the normalizer fails, the Version is quarantined with a Diagnostic on the Version read (or, on an optional text/* route, published through the built-in text path with provenance.normalization.fallback). Other media types are rejected with unverified_blob. provenance.normalization is engine-owned and rejected on input. Extension namespaces owned by the pinned plugin are written only by its normalizer output, published on the Version; a submission writing one, top-level or on a Part, is rejected with 422 extension_namespace_owned.

`WithdrawalCommand`

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`source`	`SourceIdentity`	yes
`reason`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  source:
    $ref: '#/components/schemas/SourceIdentity'
  reason:
    type: string
    minLength: 1
required:
  - idempotency_key
  - source

`Availability`

Field	Type	Required	Description
`state`	string	yes	One of `materialized`, `building_baseline`, `retrieval_ready`, `quarantined`.
`is_current`	boolean	yes
`searchable`	boolean	yes

Full schema

type: object
additionalProperties: false
properties:
  state:
    type: string
    enum:
      - materialized
      - building_baseline
      - retrieval_ready
      - quarantined
  is_current:
    type: boolean
  searchable:
    type: boolean
required:
  - state
  - is_current
  - searchable

`Receipt`

Durable acceptance outcome, not workflow state. Availability is a separate authorized live read view; omitted before a linked version exists. Infrastructure retry never resolves a Receipt as failed.

Field	Type	Required	Description
`receipt_id`	string	yes	Minimum length `1`.
`state`	string	yes	One of `pending`, `resolved`.
`outcome`	string		One of `created`, `duplicate`, `withdrawal_applied`, `conflict`.
`record_id`	string		Minimum length `1`.
`version_id`	string		Minimum length `1`.
`availability`	`Availability`
`diagnostics`	array of `Error`	yes	At most `20` items.
`source`	`SourceIdentity`	yes
`processing`	`ProcessingSummary`	yes

Further rules (conditional requirements or combinations) are in the full schema below. Example pending_receipt:

{
  "receipt_id": "receipt_1",
  "source": {
    "corpus_id": "corpus_news",
    "namespace": "example-feed",
    "record_key": "article-123"
  },
  "state": "pending",
  "processing": {
    "state": "queued",
    "phase": "materialization"
  },
  "diagnostics": []
}

Example resolved_receipt:

{
  "receipt_id": "receipt_1",
  "source": {
    "corpus_id": "corpus_news",
    "namespace": "example-feed",
    "record_key": "article-123"
  },
  "state": "resolved",
  "processing": {
    "state": "running",
    "phase": "baseline"
  },
  "diagnostics": [],
  "outcome": "created",
  "record_id": "record_1",
  "version_id": "version_2",
  "availability": {
    "state": "building_baseline",
    "is_current": false,
    "searchable": false
  }
}

Full schema

type: object
additionalProperties: false
properties:
  receipt_id:
    type: string
    minLength: 1
  state:
    type: string
    enum:
      - pending
      - resolved
  outcome:
    type: string
    enum:
      - created
      - duplicate
      - withdrawal_applied
      - conflict
  record_id:
    type: string
    minLength: 1
  version_id:
    type: string
    minLength: 1
  availability:
    $ref: '#/components/schemas/Availability'
  diagnostics:
    type: array
    items:
      $ref: '#/components/schemas/Error'
    maxItems: 20
  source:
    $ref: '#/components/schemas/SourceIdentity'
  processing:
    $ref: '#/components/schemas/ProcessingSummary'
required:
  - receipt_id
  - state
  - diagnostics
  - source
  - processing
description: Durable acceptance outcome, not workflow state. Availability is a separate authorized live read view; omitted before a linked version exists. Infrastructure retry never resolves a Receipt as failed.
if:
  properties:
    state:
      const: pending
then:
  not:
    required:
      - outcome
else:
  required:
    - outcome

`BatchRequest`

Envelope validation checks items array and batch/body limits only. Each raw entry is independently validated as IngestCommand; even a missing required field or wrong JSON type returns an entry error. SDK convenience builders may type valid entries as IngestCommand, but server envelope validation must not reject the entire batch for an invalid entry.

Field	Type	Required	Description
`items`	array of any	yes	At least `1` items. At most `100` items.

Example mixed_batch_input:

{
  "items": [
    {
      "idempotency_key": "import-42:item-7",
      "source": {
        "corpus_id": "corpus_news",
        "namespace": "example-feed",
        "record_key": "article-123"
      },
      "source_revision": "2",
      "content": {
        "kind": "text",
        "text": "Le texte de la dépêche…"
      },
      "extensions": {
        "example.editorial": {
          "schema_version": "1",
          "data": {
            "headline": "Titre échantillon",
            "subjects": [
              {
                "code": "science",
                "score": 0.75
              }
            ],
            "flags": {
              "urgent": true
            },
            "extra": null
          }
        }
      }
    },
    {
      "source": {
        "corpus_id": "corpus_news",
        "namespace": "example-feed",
        "record_key": "article-123"
      }
    },
    42
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items: {}
    minItems: 1
    maxItems: 100
required:
  - items
description: Envelope validation checks items array and batch/body limits only. Each raw entry is independently validated as IngestCommand; even a missing required field or wrong JSON type returns an entry error. SDK convenience builders may type valid entries as IngestCommand, but server envelope validation must not reject the entire batch for an invalid entry.

`BatchItem`

Field	Type	Required	Description
`index`	integer	yes	Minimum `0`.
`receipt`	`Receipt`
`error`	`Error`

Further rules (conditional requirements or combinations) are in the full schema below.

Full schema

type: object
additionalProperties: false
properties:
  index:
    type: integer
    minimum: 0
  receipt:
    $ref: '#/components/schemas/Receipt'
  error:
    $ref: '#/components/schemas/Error'
required:
  - index
if:
  required:
    - receipt
then:
  not:
    required:
      - error
else:
  required:
    - error

`BatchResult`

Field	Type	Required	Description
`items`	array of `BatchItem`	yes	At most `100` items.

Example mixed_batch_result:

{
  "items": [
    {
      "index": 0,
      "receipt": {
        "receipt_id": "receipt_1",
        "source": {
          "corpus_id": "corpus_news",
          "namespace": "example-feed",
          "record_key": "article-123"
        },
        "state": "pending",
        "processing": {
          "state": "queued",
          "phase": "materialization"
        },
        "diagnostics": []
      }
    },
    {
      "index": 1,
      "error": {
        "code": "invalid_schema",
        "message": "invalid schema",
        "retryable": false
      }
    },
    {
      "index": 2,
      "error": {
        "code": "invalid_schema",
        "message": "invalid schema",
        "retryable": false
      }
    }
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/BatchItem'
    maxItems: 100
required:
  - items

`Record`

Field	Type	Required	Description
`record_id`	string	yes	Minimum length `1`.
`source`	`SourceIdentity`	yes
`withdrawn`	boolean	yes
`current_version_id`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  record_id:
    type: string
    minLength: 1
  source:
    $ref: '#/components/schemas/SourceIdentity'
  withdrawn:
    type: boolean
  current_version_id:
    type: string
    minLength: 1
required:
  - record_id
  - source
  - withdrawn

`Version`

Field	Type	Required	Description
`record_id`	string	yes	Minimum length `1`.
`version_id`	string	yes	Minimum length `1`.
`accepted_at`	string (date-time)		When Quivr accepted the revision this Version publishes, before any processing.
`manifest`	`ManifestContent`	yes
`extensions`	`Extensions`
`provenance`	`Provenance`
`availability`	`Availability`	yes
`relations`	array of `ResolvedRelation`	yes
`processing`	`ProcessingSummary`	yes
`diagnostics`	array of `Diagnostic`		Why the Version needs attention. A quarantined Version lists its reason first. A Version published through an optional route’s fallback lists the normalizer failure it fell back from, and a recorded normalizer_conflict is listed on the Version whose output was kept. Omitted when there is nothing to report. At most `20` items.

Example version_relations:

{
  "record_id": "record_1",
  "version_id": "version_2",
  "accepted_at": "2026-09-29T10:00:00Z",
  "manifest": {
    "kind": "manifest",
    "parts": [
      {
        "key": "body",
        "role": "body",
        "content": {
          "kind": "text",
          "text": "Texte"
        },
        "extensions": {
          "example.editorial": {
            "schema_version": "1",
            "data": {
              "headline": "Titre échantillon",
              "subjects": [
                {
                  "code": "science",
                  "score": 0.75
                }
              ],
              "flags": {
                "urgent": true
              },
              "extra": null
            }
          }
        }
      },
      {
        "key": "source",
        "role": "source",
        "content": {
          "kind": "blob",
          "blob_id": "blob_original",
          "media_type": "application/xml"
        }
      }
    ],
    "relations": [
      {
        "type": "illustrated_by",
        "target": {
          "corpus_id": "corpus_news",
          "namespace": "example-feed",
          "record_key": "photo-8"
        },
        "source_target_revision": "1"
      }
    ]
  },
  "extensions": {
    "example.editorial": {
      "schema_version": "1",
      "data": {
        "headline": "Titre échantillon",
        "subjects": [
          {
            "code": "science",
            "score": 0.75
          }
        ],
        "flags": {
          "urgent": true
        },
        "extra": null
      }
    }
  },
  "availability": {
    "state": "retrieval_ready",
    "is_current": true,
    "searchable": true
  },
  "processing": {
    "state": "idle"
  },
  "relations": [
    {
      "source_reference": {
        "type": "illustrated_by",
        "target": {
          "corpus_id": "corpus_news",
          "namespace": "example-feed",
          "record_key": "photo-8"
        },
        "source_target_revision": "1"
      },
      "status": "available",
      "target_record_id": "photo_record",
      "target_version_id": "photo_version_2"
    },
    {
      "source_reference": {
        "type": "illustrated_by",
        "target": {
          "corpus_id": "corpus_news",
          "namespace": "example-feed",
          "record_key": "photo-missing"
        },
        "source_target_revision": "1"
      },
      "status": "unavailable"
    }
  ]
}

Example quarantined_version:

{
  "record_id": "record_2",
  "version_id": "version_3",
  "manifest": {
    "kind": "manifest",
    "parts": [
      {
        "key": "source",
        "role": "source",
        "content": {
          "kind": "blob",
          "blob_id": "blob_markdown",
          "media_type": "text/markdown"
        }
      }
    ]
  },
  "provenance": {
    "source_blob_ids": [
      "blob_markdown"
    ]
  },
  "availability": {
    "state": "quarantined",
    "is_current": false,
    "searchable": false
  },
  "processing": {
    "state": "blocked",
    "phase": "baseline"
  },
  "relations": [],
  "diagnostics": [
    {
      "code": "normalizer_invalid_output",
      "message": "invalid normalizer output: duplicate Part key",
      "retryable": false,
      "plugin": "example.markdown",
      "contribution": "normalizer",
      "invocation_id": "inv_1"
    }
  ]
}

Example fallback_version:

{
  "record_id": "record_3",
  "version_id": "version_4",
  "manifest": {
    "kind": "manifest",
    "parts": [
      {
        "key": "body",
        "role": "body",
        "content": {
          "kind": "text",
          "text": "# Title\n\nBody"
        }
      }
    ]
  },
  "provenance": {
    "source_blob_ids": [
      "blob_markdown_2"
    ],
    "normalization": {
      "plugin_id": "example.markdown",
      "plugin_version": "1.0.0",
      "plugin_api": "0.1.0",
      "contribution": "normalizer",
      "invocation_id": "inv_2",
      "idempotency_key": "nk_1",
      "input_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "fallback": {
        "code": "normalizer_failed",
        "message": "The normalizer refused the input with unreadable: cannot read"
      }
    }
  },
  "availability": {
    "state": "retrieval_ready",
    "is_current": true,
    "searchable": true
  },
  "processing": {
    "state": "idle"
  },
  "relations": [],
  "diagnostics": [
    {
      "code": "normalizer_failed",
      "message": "The normalizer refused the input with unreadable: cannot read",
      "retryable": false,
      "plugin": "example.markdown",
      "contribution": "normalizer",
      "invocation_id": "inv_2"
    }
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  record_id:
    type: string
    minLength: 1
  version_id:
    type: string
    minLength: 1
  accepted_at:
    type: string
    format: date-time
    description: When Quivr accepted the revision this Version publishes, before any processing.
  manifest:
    $ref: '#/components/schemas/ManifestContent'
  extensions:
    $ref: '#/components/schemas/Extensions'
  provenance:
    $ref: '#/components/schemas/Provenance'
  availability:
    $ref: '#/components/schemas/Availability'
  relations:
    type: array
    items:
      $ref: '#/components/schemas/ResolvedRelation'
  processing:
    $ref: '#/components/schemas/ProcessingSummary'
  diagnostics:
    type: array
    items:
      $ref: '#/components/schemas/Diagnostic'
    maxItems: 20
    description: Why the Version needs attention. A quarantined Version lists its reason first. A Version published through an optional route's fallback lists the normalizer failure it fell back from, and a recorded normalizer_conflict is listed on the Version whose output was kept. Omitted when there is nothing to report.
required:
  - record_id
  - version_id
  - manifest
  - availability
  - relations
  - processing

`UploadRequest`

Field	Type	Required	Description
`size_bytes`	integer	yes	Minimum `1`. Maximum `1073741824`.
`sha256`	string	yes	Pattern `^[a-f0-9]{64}$`.
`media_type`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  size_bytes:
    type: integer
    minimum: 1
    maximum: 1073741824
  sha256:
    type: string
    pattern: ^[a-f0-9]{64}$
  media_type:
    type: string
    minLength: 1
required:
  - size_bytes
  - sha256
  - media_type

`Upload`

Upload URL and headers are transfer capabilities. Only verified uploads expose a usable Blob ID. Repeated confirmation of the same session observes the same verification, never a second upload.

Field	Type	Required	Description
`upload_id`	string	yes	Minimum length `1`.
`state`	string	yes	One of `awaiting_upload`, `verifying`, `verified`, `rejected`, `expired`.
`upload_url`	string (uri)
`upload_headers`	map of string
`expires_at`	string (date-time)
`blob_id`	string		Minimum length `1`.
`error`	`Error`
`upload_method`	string		One of `PUT`.

Further rules (conditional requirements or combinations) are in the full schema below. Example verified_upload:

{
  "upload_id": "upload_1",
  "state": "verified",
  "blob_id": "blob_text"
}

Full schema

type: object
additionalProperties: false
properties:
  upload_id:
    type: string
    minLength: 1
  state:
    type: string
    enum:
      - awaiting_upload
      - verifying
      - verified
      - rejected
      - expired
  upload_url:
    type: string
    format: uri
  upload_headers:
    type: object
    additionalProperties:
      type: string
  expires_at:
    type: string
    format: date-time
  blob_id:
    type: string
    minLength: 1
  error:
    $ref: '#/components/schemas/Error'
  upload_method:
    type: string
    enum:
      - PUT
required:
  - upload_id
  - state
description: Upload URL and headers are transfer capabilities. Only verified uploads expose a usable Blob ID. Repeated confirmation of the same session observes the same verification, never a second upload.
allOf:
  - if:
      properties:
        state:
          const: verified
    then:
      required:
        - blob_id
    else:
      not:
        required:
          - blob_id

`Blob`

Field	Type	Required	Description
`blob_id`	string	yes	Minimum length `1`.
`size_bytes`	integer	yes	Minimum `1`.
`sha256`	string	yes	Pattern `^[a-f0-9]{64}$`.
`media_type`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  blob_id:
    type: string
    minLength: 1
  size_bytes:
    type: integer
    minimum: 1
  sha256:
    type: string
    pattern: ^[a-f0-9]{64}$
  media_type:
    type: string
    minLength: 1
required:
  - blob_id
  - size_bytes
  - sha256
  - media_type

`Operation`

Administrative execution only. Retries keep identity. Intentional terminal rerun has a new ID and previous_operation_id. Cancellation does not promise universal rollback; already-terminal state and racing completion may win. projection_rebuild and retrieval_configuration Operations require corpus_id; when succeeded they require result naming the activated logical generation. This result shape covers those two command kinds only.

Field	Type	Required	Description
`operation_id`	string	yes	Minimum length `1`.
`kind`	string	yes	Minimum length `1`.
`state`	string	yes	One of `queued`, `running`, `succeeded`, `failed`, `cancel_requested`, `canceled`.
`progress`	number		Approximate fraction, omitted when unknown. Minimum `0`. Maximum `1`.
`counters`	map of integer	yes
`errors`	array of `Error`	yes	At most `20` items.
`previous_operation_id`	string		Minimum length `1`.
`corpus_id`	string		Minimum length `1`.
`result`	`ProjectionRebuildResult`

Further rules (conditional requirements or combinations) are in the full schema below. Example administrative_operation:

{
  "operation_id": "op_1",
  "kind": "projection_rebuild",
  "state": "cancel_requested",
  "counters": {
    "processed": 42
  },
  "errors": [],
  "corpus_id": "corpus_news"
}

Example rebuild_queued:

{
  "operation_id": "operation_1",
  "kind": "projection_rebuild",
  "corpus_id": "corpus_news",
  "state": "queued",
  "counters": {},
  "errors": []
}

Example rebuild_succeeded:

{
  "operation_id": "operation_1",
  "kind": "projection_rebuild",
  "corpus_id": "corpus_news",
  "state": "succeeded",
  "counters": {
    "indexed": 24
  },
  "errors": [],
  "result": {
    "projection_generation_id": "generation_2"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  operation_id:
    type: string
    minLength: 1
  kind:
    type: string
    minLength: 1
  state:
    type: string
    enum:
      - queued
      - running
      - succeeded
      - failed
      - cancel_requested
      - canceled
  progress:
    type: number
    minimum: 0
    maximum: 1
    description: Approximate fraction, omitted when unknown.
  counters:
    type: object
    additionalProperties:
      type: integer
      minimum: 0
  errors:
    type: array
    items:
      $ref: '#/components/schemas/Error'
    maxItems: 20
  previous_operation_id:
    type: string
    minLength: 1
  corpus_id:
    type: string
    minLength: 1
  result:
    $ref: '#/components/schemas/ProjectionRebuildResult'
required:
  - operation_id
  - kind
  - state
  - counters
  - errors
description: Administrative execution only. Retries keep identity. Intentional terminal rerun has a new ID and previous_operation_id. Cancellation does not promise universal rollback; already-terminal state and racing completion may win. projection_rebuild and retrieval_configuration Operations require corpus_id; when succeeded they require result naming the activated logical generation. This result shape covers those two command kinds only.
if:
  properties:
    kind:
      enum:
        - projection_rebuild
        - retrieval_configuration
  required:
    - kind
then:
  required:
    - corpus_id
  if:
    properties:
      state:
        const: succeeded
    required:
      - state
  then:
    required:
      - result

`FieldMapping`

v0 logical field mapping. name is a logical name matching ^[a-z][a-z0-9_]{0,63}$, never a search-engine field name. source_pointer is an RFC 6901 JSON Pointer into the canonical source view of a Version, rooted at /manifest, /provenance or /extensions/{namespace} with a declared namespace (built in, or owned by the startup-pinned plugin); other roots are rejected as invalid_mapping. Core validates role/type compatibility (search requires string or string_array). A search field named title replaces the projected title; other search fields add text once per Record Version. Filter roles are validated and preserved; no public filter API consumes them in v0.

Field	Type	Required	Description
`name`	string	yes	Minimum length `1`.
`source_pointer`	string	yes	Minimum length `1`.
`type`	string	yes	One of `string`, `number`, `boolean`, `datetime`, `string_array`.
`roles`	array of string	yes	At least `1` items. Each item: One of `search`, `filter`.

Full schema

type: object
additionalProperties: false
properties:
  name:
    type: string
    minLength: 1
  source_pointer:
    type: string
    minLength: 1
  type:
    type: string
    enum:
      - string
      - number
      - boolean
      - datetime
      - string_array
  roles:
    type: array
    items:
      type: string
      enum:
        - search
        - filter
    minItems: 1
required:
  - name
  - source_pointer
  - type
  - roles
description: v0 logical field mapping. name is a logical name matching ^[a-z][a-z0-9_]{0,63}$, never a search-engine field name. source_pointer is an RFC 6901 JSON Pointer into the canonical source view of a Version, rooted at /manifest, /provenance or /extensions/{namespace} with a declared namespace (built in, or owned by the startup-pinned plugin); other roots are rejected as invalid_mapping. Core validates role/type compatibility (search requires string or string_array). A search field named title replaces the projected title; other search fields add text once per Record Version. Filter roles are validated and preserved; no public filter API consumes them in v0.

`RetrievalConfig`

Pin a plugin-provided profile when resolving config. Explicit fields override default fields by logical name; unmapped source data remains preserved. getCorpus returns the effective resolved fields. The only built-in profile, example.editorial, is illustrative (paired with the example extension namespace), not a product default; an uninstalled profile is 422 unsupported_profile.

Field	Type	Required	Description
`plugin_profile`	string		Minimum length `1`.
`fields`	array of `FieldMapping`

Full schema

type: object
additionalProperties: false
properties:
  plugin_profile:
    type: string
    minLength: 1
  fields:
    type: array
    items:
      $ref: '#/components/schemas/FieldMapping'
required: []
description: Pin a plugin-provided profile when resolving config. Explicit fields override default fields by logical name; unmapped source data remains preserved. getCorpus returns the effective resolved fields. The only built-in profile, example.editorial, is illustrative (paired with the example extension namespace), not a product default; an uninstalled profile is 422 unsupported_profile.

`ConnectorKind`

Connector kind, provided by the engine or by a pinned connector plugin; listConnectorKinds lists the kinds this deployment accepts. Built-in kinds are fixture (a deterministic test connector available only when the deployment enables it). First-party connector plugins provide rss (RSS 2.0, RSS 1.0, Atom and JSON Feed documents; config url, optional honor_ttl; optional credential username+password or token), x_list (an X list) and m365_mail (Microsoft 365 mailboxes). Another kind is refused with 422 unsupported_connector_kind. Type: string. Pattern ^[a-z][a-z0-9_]{0,31}$.

Full schema

type: string
pattern: ^[a-z][a-z0-9_]{0,31}$
description: Connector kind, provided by the engine or by a pinned connector plugin; listConnectorKinds lists the kinds this deployment accepts. Built-in kinds are fixture (a deterministic test connector available only when the deployment enables it). First-party connector plugins provide rss (RSS 2.0, RSS 1.0, Atom and JSON Feed documents; config url, optional honor_ttl; optional credential username+password or token), x_list (an X list) and m365_mail (Microsoft 365 mailboxes). Another kind is refused with 422 unsupported_connector_kind.

`CredentialDeposit`

Field	Type	Required	Description
`secret`	object	yes	Kind-specific secret, validated by the kind’s credential JSON Schema, encrypted at rest with the deployment credential key and never returned or logged. Without a configured credential key the request is refused with 503 credentials_unavailable. Write-only.
`expires_at`	string (date-time)

Full schema

type: object
additionalProperties: false
properties:
  secret:
    type: object
    writeOnly: true
    description: Kind-specific secret, validated by the kind's credential JSON Schema, encrypted at rest with the deployment credential key and never returned or logged. Without a configured credential key the request is refused with 503 credentials_unavailable.
  expires_at:
    type: string
    format: date-time
required:
  - secret

`CredentialReplace`

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`secret`	object	yes	Write-only.
`expires_at`	string (date-time)

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  secret:
    type: object
    writeOnly: true
  expires_at:
    type: string
    format: date-time
required:
  - idempotency_key
  - secret

`ConnectorSchedule`

Field	Type	Required	Description
`interval_seconds`	integer		Polling interval. Defaults per kind (fixture/rss 300, m365_mail 60, x_list 120); values below the deployment floor (30 s by default) are 422 invalid_interval. Minimum `1`. Maximum `86400`.

Full schema

type: object
additionalProperties: false
properties:
  interval_seconds:
    type: integer
    minimum: 1
    maximum: 86400
    description: Polling interval. Defaults per kind (fixture/rss 300, m365_mail 60, x_list 120); values below the deployment floor (30 s by default) are 422 invalid_interval.

`ConnectorRunRequest`

Field	Type	Required	Description
`connector_id`	string	yes
`run_at`	string (date-time)	yes	When the requested run is due; now unless the interval floor or the source’s Retry-After defers it.

Full schema

type: object
additionalProperties: false
properties:
  connector_id:
    type: string
  run_at:
    type: string
    format: date-time
    description: When the requested run is due; now unless the interval floor or the source's Retry-After defers it.
required:
  - connector_id
  - run_at

`ScheduleChange`

Field	Type	Required	Description
`interval_seconds`	integer	yes	Seconds between runs. Bounds are the deployment floor and 86400; values outside them are 422 invalid_interval with field /interval_seconds.

Example connector_schedule_change:

{
  "interval_seconds": 600
}

Full schema

type: object
additionalProperties: false
properties:
  interval_seconds:
    type: integer
    description: Seconds between runs. Bounds are the deployment floor and 86400; values outside them are 422 invalid_interval with field /interval_seconds.
required:
  - interval_seconds

`ConnectorKindDescription`

Field	Type	Required	Description
`kind`	string	yes	Kind identifier accepted by createConnector for this deployment. A plain string so kinds added by future providers need no contract change here. Minimum length `1`.
`title`	string	yes	Display name, from the config schema’s title annotation (the kind when absent). Minimum length `1`.
`description`	string		Short explanation, from the config schema’s description annotation.
`config_schema`	object	yes	JSON Schema (2020-12) validating config. Annotations (title, description, examples) are informational.
`credential_schema`	object		JSON Schema validating credential.secret. Members annotated writeOnly are secrets. Absent when the kind takes no credential.
`credential`	string	yes	Whether an instance of this kind takes, may take or needs a Deposited Credential. One of `none`, `optional`, `required`.
`default_interval_seconds`	integer	yes	Minimum `1`.

Full schema

type: object
additionalProperties: false
properties:
  kind:
    type: string
    minLength: 1
    description: Kind identifier accepted by createConnector for this deployment. A plain string so kinds added by future providers need no contract change here.
  title:
    type: string
    minLength: 1
    description: Display name, from the config schema's title annotation (the kind when absent).
  description:
    type: string
    description: Short explanation, from the config schema's description annotation.
  config_schema:
    type: object
    description: JSON Schema (2020-12) validating config. Annotations (title, description, examples) are informational.
  credential_schema:
    type: object
    description: JSON Schema validating credential.secret. Members annotated writeOnly are secrets. Absent when the kind takes no credential.
  credential:
    type: string
    enum:
      - none
      - optional
      - required
    description: Whether an instance of this kind takes, may take or needs a Deposited Credential.
  default_interval_seconds:
    type: integer
    minimum: 1
required:
  - kind
  - title
  - config_schema
  - credential
  - default_interval_seconds

`PluginRegistration`

Field	Type	Required	Description
`registration_id`	string	yes	Minimum length `1`.
`plugin_id`	string	yes	Minimum length `1`.
`version`	string	yes	Minimum length `1`.
`endpoint`	string	yes	Base URL where the operator runs this plugin version. Minimum length `1`.
`manifest_digest`	string	yes	Minimum length `1`.
`artifact_digest`	string		Artifact digest the plugin reports, recorded as information. Absent when it reports none. Minimum length `1`.
`contributions`	array of string	yes
`roles`	array of string	yes	Roles the manifest declares it can serve, such as normalizer:application/pdf, subscription:<plugin id> or connector:<kind>. The active plan says which it serves.
`state`	string	yes	One of `registered`, `validated`, `active`, `draining`, `inactive`, `rejected`.
`created_at`	string (date-time)	yes
`updated_at`	string (date-time)	yes

Full schema

type: object
additionalProperties: false
properties:
  registration_id:
    type: string
    minLength: 1
  plugin_id:
    type: string
    minLength: 1
  version:
    type: string
    minLength: 1
  endpoint:
    type: string
    minLength: 1
    description: Base URL where the operator runs this plugin version.
  manifest_digest:
    type: string
    minLength: 1
  artifact_digest:
    type: string
    minLength: 1
    description: Artifact digest the plugin reports, recorded as information. Absent when it reports none.
  contributions:
    type: array
    items:
      type: string
  roles:
    type: array
    items:
      type: string
    description: Roles the manifest declares it can serve, such as normalizer:application/pdf, subscription:<plugin id> or connector:<kind>. The active plan says which it serves.
  state:
    type: string
    enum:
      - registered
      - validated
      - active
      - draining
      - inactive
      - rejected
  created_at:
    type: string
    format: date-time
  updated_at:
    type: string
    format: date-time
required:
  - registration_id
  - plugin_id
  - version
  - endpoint
  - manifest_digest
  - contributions
  - roles
  - state
  - created_at
  - updated_at

`PluginRegistrationList`

Field	Type	Required	Description
`items`	array of `PluginRegistration`	yes

Example plugin_registrations:

{
  "items": [
    {
      "registration_id": "plugin_registration_3f1c",
      "plugin_id": "pdf-text",
      "version": "0.1.0",
      "endpoint": "http://127.0.0.1:9900",
      "manifest_digest": "sha256:5b2e",
      "contributions": [
        "normalizer"
      ],
      "roles": [
        "normalizer:application/pdf"
      ],
      "state": "active",
      "created_at": "2026-09-30T10:00:00Z",
      "updated_at": "2026-09-30T10:00:00Z"
    },
    {
      "registration_id": "plugin_registration_9a7d",
      "plugin_id": "connector.rss",
      "version": "1.0.0",
      "endpoint": "http://127.0.0.1:9920",
      "manifest_digest": "sha256:c41a",
      "artifact_digest": "sha256:0d9e",
      "contributions": [
        "connector"
      ],
      "roles": [
        "connector:rss"
      ],
      "state": "active",
      "created_at": "2026-09-30T10:00:00Z",
      "updated_at": "2026-09-30T10:00:00Z"
    }
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/PluginRegistration'
required:
  - items

`PipelinePlanRole`

Field	Type	Required	Description
`role`	string	yes	Minimum length `1`.
`registration_id`	string	yes	Minimum length `1`.
`plugin_id`	string	yes	Minimum length `1`.
`version`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  role:
    type: string
    minLength: 1
  registration_id:
    type: string
    minLength: 1
  plugin_id:
    type: string
    minLength: 1
  version:
    type: string
    minLength: 1
required:
  - role
  - registration_id
  - plugin_id
  - version

`PipelinePlan`

Field	Type	Required	Description
`plan_id`	string	yes	Minimum length `1`.
`created_at`	string (date-time)	yes
`activated_at`	string (date-time)	yes
`roles`	array of `PipelinePlanRole`	yes	One entry per role, sorted by role.

Example pipeline_plan:

{
  "plan_id": "plan_6e0b",
  "created_at": "2026-09-30T10:00:00Z",
  "activated_at": "2026-09-30T10:00:00Z",
  "roles": [
    {
      "role": "connector:rss",
      "registration_id": "plugin_registration_9a7d",
      "plugin_id": "connector.rss",
      "version": "1.0.0"
    },
    {
      "role": "normalizer:application/pdf",
      "registration_id": "plugin_registration_3f1c",
      "plugin_id": "pdf-text",
      "version": "0.1.0"
    }
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  plan_id:
    type: string
    minLength: 1
  created_at:
    type: string
    format: date-time
  activated_at:
    type: string
    format: date-time
  roles:
    type: array
    description: One entry per role, sorted by role.
    items:
      $ref: '#/components/schemas/PipelinePlanRole'
required:
  - plan_id
  - created_at
  - activated_at
  - roles

`ConnectorKindCatalog`

Field	Type	Required	Description
`credential_deposits`	string	yes	unavailable on a deployment without a credential key, where credential deposits and rotations are refused with 503 credentials_unavailable. One of `available`, `unavailable`.
`min_interval_seconds`	integer	yes	Shortest polling interval this deployment accepts. Minimum `1`.
`items`	array of `ConnectorKindDescription`	yes

Example connector_kinds:

{
  "credential_deposits": "available",
  "min_interval_seconds": 30,
  "items": [
    {
      "kind": "rss",
      "title": "RSS or Atom feed",
      "description": "Collects the entries of an RSS 2.0, RSS 1.0, Atom or JSON Feed document.",
      "config_schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "title": "Feed URL",
            "examples": [
              "https://example.org/feed.xml"
            ]
          },
          "honor_ttl": {
            "type": "boolean",
            "title": "Honor the feed's TTL"
          }
        }
      },
      "credential_schema": {
        "oneOf": [
          {
            "title": "Bearer token",
            "type": "object",
            "required": [
              "token"
            ],
            "properties": {
              "token": {
                "type": "string",
                "writeOnly": true
              }
            }
          }
        ]
      },
      "credential": "optional",
      "default_interval_seconds": 300
    }
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  credential_deposits:
    type: string
    enum:
      - available
      - unavailable
    description: unavailable on a deployment without a credential key, where credential deposits and rotations are refused with 503 credentials_unavailable.
  min_interval_seconds:
    type: integer
    minimum: 1
    description: Shortest polling interval this deployment accepts.
  items:
    type: array
    items:
      $ref: '#/components/schemas/ConnectorKindDescription'
required:
  - credential_deposits
  - min_interval_seconds
  - items

`ConnectorHealthPolicy`

Field	Type	Required	Description
`silent_after_seconds`	integer		No new item for this long makes the source silent. Default 86400. Minimum `1`. Maximum `2592000`.
`credential_warning_seconds`	integer		A credential expiring within this window is credential_expiring. Default 1209600. Minimum `0`. Maximum `31536000`.

Full schema

type: object
additionalProperties: false
properties:
  silent_after_seconds:
    type: integer
    minimum: 1
    maximum: 2592000
    description: No new item for this long makes the source silent. Default 86400.
  credential_warning_seconds:
    type: integer
    minimum: 0
    maximum: 31536000
    description: A credential expiring within this window is credential_expiring. Default 1209600.

`ConnectorCreate`

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`corpus_id`	string	yes	Minimum length `1`.
`source_namespace`	string	yes	Minimum length `1`. Maximum length `200`.
`kind`	`ConnectorKind`	yes
`config`	object	yes	Kind-specific configuration validated by the kind’s JSON Schema. Holds no secret.
`schedule`	`ConnectorSchedule`
`health_policy`	`ConnectorHealthPolicy`
`credential`	`CredentialDeposit`

Example connector_create:

{
  "idempotency_key": "newsroom-wire-feed",
  "corpus_id": "corpus_news",
  "source_namespace": "newsroom-wire",
  "kind": "fixture",
  "config": {
    "script": []
  },
  "schedule": {
    "interval_seconds": 300
  },
  "health_policy": {
    "silent_after_seconds": 86400,
    "credential_warning_seconds": 1209600
  },
  "credential": {
    "secret": {
      "token": "fixture-test-token"
    },
    "expires_at": "2027-01-01T00:00:00Z"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  corpus_id:
    type: string
    minLength: 1
  source_namespace:
    type: string
    minLength: 1
    maxLength: 200
  kind:
    $ref: '#/components/schemas/ConnectorKind'
  config:
    type: object
    description: Kind-specific configuration validated by the kind's JSON Schema. Holds no secret.
  schedule:
    $ref: '#/components/schemas/ConnectorSchedule'
  health_policy:
    $ref: '#/components/schemas/ConnectorHealthPolicy'
  credential:
    $ref: '#/components/schemas/CredentialDeposit'
required:
  - idempotency_key
  - corpus_id
  - source_namespace
  - kind
  - config

`CredentialMetadata`

Metadata of the current Deposited Credential; the secret itself is never returned.

Field	Type	Required	Description
`version`	integer	yes	Minimum `1`.
`deposited_at`	string (date-time)	yes
`expires_at`	string (date-time)

Full schema

type: object
additionalProperties: false
properties:
  version:
    type: integer
    minimum: 1
  deposited_at:
    type: string
    format: date-time
  expires_at:
    type: string
    format: date-time
required:
  - version
  - deposited_at
description: Metadata of the current Deposited Credential; the secret itself is never returned.

`ConnectorError`

Field	Type	Required	Description
`code`	string	yes	Minimum length `1`.
`at`	string (date-time)	yes

Full schema

type: object
additionalProperties: false
properties:
  code:
    type: string
    minLength: 1
  at:
    type: string
    format: date-time
required:
  - code
  - at

`ConnectorUsage`

Per-UTC-day source read counters, present only for kinds that report reads.

Field	Type	Required	Description
`day`	string	yes	Current UTC calendar day (YYYY-MM-DD). Pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`.
`items_read`	integer	yes	Source resources read during the current UTC day, counted as the source bills them (for x_list, an estimate of billed post reads after X’s per-UTC-day deduplication). Minimum `0`.
`previous_day_items_read`	integer	yes	Minimum `0`.

Full schema

type: object
additionalProperties: false
properties:
  day:
    type: string
    pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
    description: Current UTC calendar day (YYYY-MM-DD).
  items_read:
    type: integer
    minimum: 0
    description: Source resources read during the current UTC day, counted as the source bills them (for x_list, an estimate of billed post reads after X's per-UTC-day deduplication).
  previous_day_items_read:
    type: integer
    minimum: 0
required:
  - day
  - items_read
  - previous_day_items_read
description: Per-UTC-day source read counters, present only for kinds that report reads.

`ConnectorHealth`

Last committed Connector Health, evaluated at each acquisition run, credential replacement and disable; evaluated_at shows its age. Precedence disabled, access_error, credential_expiring, silent, active. access_error means the source refused access (distinct from silent, which means no new item within the threshold), including a push channel refused access while polling carries the collection. Other failures appear only as last_error.

Field	Type	Required	Description
`state`	string	yes	One of `active`, `silent`, `access_error`, `credential_expiring`, `disabled`.
`evaluated_at`	string (date-time)	yes
`last_success_at`	string (date-time)
`last_item_at`	string (date-time)
`last_error`	`ConnectorError`
`usage`	`ConnectorUsage`
`diagnostics`	object		Kind-defined diagnostics from the latest acquisition page, documented on the kind’s operator guide page (for x_list, the deletion recheck coverage). Informational; never holds a secret or source content.
`push`	`ConnectorPush`

Full schema

type: object
additionalProperties: false
properties:
  state:
    type: string
    enum:
      - active
      - silent
      - access_error
      - credential_expiring
      - disabled
  evaluated_at:
    type: string
    format: date-time
  last_success_at:
    type: string
    format: date-time
  last_item_at:
    type: string
    format: date-time
  last_error:
    $ref: '#/components/schemas/ConnectorError'
  usage:
    $ref: '#/components/schemas/ConnectorUsage'
  diagnostics:
    type: object
    description: Kind-defined diagnostics from the latest acquisition page, documented on the kind's operator guide page (for x_list, the deletion recheck coverage). Informational; never holds a secret or source content.
  push:
    $ref: '#/components/schemas/ConnectorPush'
required:
  - state
  - evaluated_at
description: Last committed Connector Health, evaluated at each acquisition run, credential replacement and disable; evaluated_at shows its age. Precedence disabled, access_error, credential_expiring, silent, active. access_error means the source refused access (distinct from silent, which means no new item within the threshold), including a push channel refused access while polling carries the collection. Other failures appear only as last_error.

`ConnectorPush`

Push delivery health, present once a kind that declares the push mode reports its push channel.

Field	Type	Required	Description
`state`	string	yes	active, deliveries are expected; pending, the kind has not set its push channel up yet; degraded, the setup failed or deliveries fail or miss items, and polling at the instance’s interval carries the collection. One of `active`, `pending`, `degraded`.
`error`	`ConnectorPushError`
`last_delivery_at`	string (date-time)		Last delivery the connector plugin accepted.
`poll_interval_seconds`	integer		While push is active, polling runs at most this often, as a safety net. Minimum `1`.

Full schema

type: object
additionalProperties: false
properties:
  state:
    type: string
    enum:
      - active
      - pending
      - degraded
    description: active, deliveries are expected; pending, the kind has not set its push channel up yet; degraded, the setup failed or deliveries fail or miss items, and polling at the instance's interval carries the collection.
  error:
    $ref: '#/components/schemas/ConnectorPushError'
  last_delivery_at:
    type: string
    format: date-time
    description: Last delivery the connector plugin accepted.
  poll_interval_seconds:
    type: integer
    minimum: 1
    description: While push is active, polling runs at most this often, as a safety net.
required:
  - state
description: Push delivery health, present once a kind that declares the push mode reports its push channel.

`ConnectorPushError`

Field	Type	Required	Description
`class`	string	yes	One of `access`, `transient`, `source`.
`code`	string	yes	For example webhook_invalid (the source invalidated the webhook), plugin_unavailable (a delivery found the plugin down) or missed_deliveries (polling found items no delivery brought). Minimum length `1`.
`at`	string (date-time)	yes

Full schema

type: object
additionalProperties: false
properties:
  class:
    type: string
    enum:
      - access
      - transient
      - source
  code:
    type: string
    minLength: 1
    description: For example webhook_invalid (the source invalidated the webhook), plugin_unavailable (a delivery found the plugin down) or missed_deliveries (polling found items no delivery brought).
  at:
    type: string
    format: date-time
required:
  - class
  - code
  - at

`Connector`

Field	Type	Required	Description
`connector_id`	string	yes	Minimum length `1`.
`corpus_id`	string	yes	Minimum length `1`.
`source_namespace`	string	yes	Minimum length `1`.
`kind`	`ConnectorKind`	yes
`config`	object	yes
`schedule`	object	yes
`schedule.interval_seconds`	integer	yes	Minimum `1`.
`health_policy`	object	yes
`health_policy.silent_after_seconds`	integer	yes	Minimum `1`.
`health_policy.credential_warning_seconds`	integer	yes	Minimum `0`.
`enabled`	boolean	yes
`created_at`	string (date-time)	yes
`disabled_at`	string (date-time)
`credential`	`CredentialMetadata`
`health`	`ConnectorHealth`	yes
`webhook_url`	string (uri)		Public address of the instance’s webhook route, present when its kind declares the push mode and the deployment sets public_url. The kind’s plugin registers it with the source.

Example connector:

{
  "connector_id": "connector_1",
  "corpus_id": "corpus_news",
  "source_namespace": "newsroom-wire",
  "kind": "fixture",
  "config": {
    "script": []
  },
  "schedule": {
    "interval_seconds": 300
  },
  "health_policy": {
    "silent_after_seconds": 86400,
    "credential_warning_seconds": 1209600
  },
  "enabled": true,
  "created_at": "2026-09-28T10:00:00Z",
  "credential": {
    "version": 1,
    "deposited_at": "2026-09-28T10:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z"
  },
  "health": {
    "state": "access_error",
    "evaluated_at": "2026-09-28T10:05:00Z",
    "last_success_at": "2026-09-28T10:01:00Z",
    "last_item_at": "2026-09-28T10:01:00Z",
    "last_error": {
      "code": "unauthorized",
      "at": "2026-09-28T10:05:00Z"
    }
  }
}

Example connector_x_list:

{
  "connector_id": "connector_2",
  "corpus_id": "corpus_news",
  "source_namespace": "x-watchlist",
  "kind": "x_list",
  "config": {
    "list_id": "1234567890123456789",
    "recheck_window_seconds": 86400
  },
  "schedule": {
    "interval_seconds": 120
  },
  "health_policy": {
    "silent_after_seconds": 86400,
    "credential_warning_seconds": 1209600
  },
  "enabled": true,
  "created_at": "2026-09-28T10:00:00Z",
  "credential": {
    "version": 1,
    "deposited_at": "2026-09-28T10:00:00Z",
    "expires_at": "2027-06-01T00:00:00Z"
  },
  "health": {
    "state": "active",
    "evaluated_at": "2026-09-28T10:06:00Z",
    "last_success_at": "2026-09-28T10:06:00Z",
    "last_item_at": "2026-09-28T10:04:00Z",
    "last_error": {
      "code": "rate_limited",
      "at": "2026-09-28T10:02:00Z"
    },
    "usage": {
      "day": "2026-09-28",
      "items_read": 412,
      "previous_day_items_read": 1830
    },
    "diagnostics": {
      "recheck_window_seconds": 86400,
      "recheck_interval_seconds": 600,
      "recheck_tracked_posts": 37,
      "recheck_dropped_posts": 0,
      "last_recheck_at": "2026-09-28T10:00:00Z"
    }
  }
}

Full schema

type: object
additionalProperties: false
properties:
  connector_id:
    type: string
    minLength: 1
  corpus_id:
    type: string
    minLength: 1
  source_namespace:
    type: string
    minLength: 1
  kind:
    $ref: '#/components/schemas/ConnectorKind'
  config:
    type: object
  schedule:
    type: object
    additionalProperties: false
    properties:
      interval_seconds:
        type: integer
        minimum: 1
    required:
      - interval_seconds
  health_policy:
    type: object
    additionalProperties: false
    properties:
      silent_after_seconds:
        type: integer
        minimum: 1
      credential_warning_seconds:
        type: integer
        minimum: 0
    required:
      - silent_after_seconds
      - credential_warning_seconds
  enabled:
    type: boolean
  created_at:
    type: string
    format: date-time
  disabled_at:
    type: string
    format: date-time
  credential:
    $ref: '#/components/schemas/CredentialMetadata'
  health:
    $ref: '#/components/schemas/ConnectorHealth'
  webhook_url:
    type: string
    format: uri
    description: Public address of the instance's webhook route, present when its kind declares the push mode and the deployment sets public_url. The kind's plugin registers it with the source.
required:
  - connector_id
  - corpus_id
  - source_namespace
  - kind
  - config
  - schedule
  - health_policy
  - enabled
  - created_at
  - health

`ConnectorPage`

Field	Type	Required	Description
`items`	array of `Connector`	yes
`next_page_cursor`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/Connector'
  next_page_cursor:
    type: string
    minLength: 1
required:
  - items

`CorpusRequest`

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`name`	string	yes	Minimum length `1`.
`retrieval`	`RetrievalConfig`

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
  retrieval:
    $ref: '#/components/schemas/RetrievalConfig'
required:
  - idempotency_key
  - name

`Corpus`

Field	Type	Required	Description
`corpus_id`	string	yes	Minimum length `1`.
`name`	string	yes	Minimum length `1`.
`effective_retrieval`	`RetrievalConfig`	yes

Full schema

type: object
additionalProperties: false
properties:
  corpus_id:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
  effective_retrieval:
    $ref: '#/components/schemas/RetrievalConfig'
required:
  - corpus_id
  - name
  - effective_retrieval

`VectorSpaceList`

Field	Type	Required	Description
`projection_generation_id`	string	yes	Minimum length `1`.
`segments`	integer	yes	Current segments the generation projects; a space whose coverage equals it holds a vector for every one. Minimum `0`.
`items`	array of `VectorSpace`	yes

Full schema

type: object
additionalProperties: false
properties:
  projection_generation_id:
    type: string
    minLength: 1
  segments:
    type: integer
    minimum: 0
    description: Current segments the generation projects; a space whose coverage equals it holds a vector for every one.
  items:
    type: array
    items:
      $ref: '#/components/schemas/VectorSpace'
required:
  - projection_generation_id
  - segments
  - items

`VectorSpace`

Field	Type	Required	Description
`vector_space_id`	string	yes	The space’s identity, as search hits report it. A plugin space is <name>@<version>. Minimum length `1`.
`name`	string	yes	Minimum length `1`.
`version`	string	yes
`owner`	object	yes
`owner.kind`	string	yes	One of `engine`, `plugin`.
`owner.plugin_id`	string		Minimum length `1`.
`owner.plugin_version`	string		Minimum length `1`.
`model`	string	yes
`dimensions`	integer	yes	Minimum `0`.
`metric`	string	yes	One of `cosine`, `dot`, `l2`.
`indexes`	array of string	yes
`query_modalities`	array of string	yes
`role`	string	yes	One of `served`, `evaluation`.
`coverage`	object	yes
`coverage.segments`	integer	yes	Minimum `0`.

Full schema

type: object
additionalProperties: false
properties:
  vector_space_id:
    type: string
    minLength: 1
    description: The space's identity, as search hits report it. A plugin space is <name>@<version>.
  name:
    type: string
    minLength: 1
  version:
    type: string
  owner:
    type: object
    additionalProperties: false
    properties:
      kind:
        type: string
        enum:
          - engine
          - plugin
      plugin_id:
        type: string
        minLength: 1
      plugin_version:
        type: string
        minLength: 1
    required:
      - kind
  model:
    type: string
  dimensions:
    type: integer
    minimum: 0
  metric:
    type: string
    enum:
      - cosine
      - dot
      - l2
  indexes:
    type: array
    items:
      type: string
  query_modalities:
    type: array
    items:
      type: string
  role:
    type: string
    enum:
      - served
      - evaluation
  coverage:
    type: object
    additionalProperties: false
    properties:
      segments:
        type: integer
        minimum: 0
    required:
      - segments
required:
  - vector_space_id
  - name
  - version
  - owner
  - model
  - dimensions
  - metric
  - indexes
  - query_modalities
  - role
  - coverage

`CorpusPage`

Field	Type	Required	Description
`items`	array of `Corpus`	yes
`next_page_cursor`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/Corpus'
  next_page_cursor:
    type: string
    minLength: 1
required:
  - items

`RecordPage`

Field	Type	Required	Description
`items`	array of `Record`	yes
`next_page_cursor`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/Record'
  next_page_cursor:
    type: string
    minLength: 1
required:
  - items

`ConfigUpdate`

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`retrieval`	`RetrievalConfig`	yes

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  retrieval:
    $ref: '#/components/schemas/RetrievalConfig'
required:
  - idempotency_key
  - retrieval

`ActionRequest`

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
required:
  - idempotency_key

`RenameRequest`

New display name of a Saved Query or Subscription.

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`name`	string	yes	Minimum length `1`.

Example rename:

{
  "idempotency_key": "rename-1",
  "name": "Storms and hail"
}

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
required:
  - idempotency_key
  - name
description: New display name of a Saved Query or Subscription.

`ResourceReference`

Field	Type	Required	Description
`kind`	string	yes	Minimum length `1`.
`id`	string	yes	Minimum length `1`.
`corpus_id`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  kind:
    type: string
    minLength: 1
  id:
    type: string
    minLength: 1
  corpus_id:
    type: string
    minLength: 1
required:
  - kind
  - id

`ChangeEvent`

Every change to a Record catalog entry emits an event with resource.kind=record and resource.id=the affected Record ID. Additional resource-specific events do not replace this invalidation. Consumers reread current state; payload detail belongs to THE-547. Monitoring notice types mirror WebhookEvent and include monitoring references; event_id identifies that same committed notice. Delivery status changes emit delivery.updated events only to the feed, never recursive webhooks.

Field	Type	Required	Description
`event_id`	string	yes	Minimum length `1`.
`type`	string	yes	Minimum length `1`.
`schema_version`	string	yes	Minimum length `1`.
`occurred_at`	string (date-time)	yes
`resource`	`ResourceReference`	yes
`cursor`	string	yes	Minimum length `1`.
`monitoring`	`MonitoringReferences`

Example monitoring_change:

{
  "event_id": "event_match_1",
  "type": "match.created",
  "schema_version": "1",
  "occurred_at": "2026-09-14T12:00:00Z",
  "resource": {
    "kind": "match",
    "id": "match_1",
    "corpus_id": "corpus_news"
  },
  "cursor": "opaque_cursor",
  "monitoring": {
    "match_id": "match_1",
    "record_id": "record_1",
    "record_version_id": "version_1",
    "subscription_id": "subscription_1",
    "subscription_version_id": "subscription_version_1",
    "delivery_id": "delivery_1"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  event_id:
    type: string
    minLength: 1
  type:
    type: string
    minLength: 1
  schema_version:
    type: string
    minLength: 1
  occurred_at:
    type: string
    format: date-time
  resource:
    $ref: '#/components/schemas/ResourceReference'
  cursor:
    type: string
    minLength: 1
  monitoring:
    $ref: '#/components/schemas/MonitoringReferences'
required:
  - event_id
  - type
  - schema_version
  - occurred_at
  - resource
  - cursor
description: Every change to a Record catalog entry emits an event with resource.kind=record and resource.id=the affected Record ID. Additional resource-specific events do not replace this invalidation. Consumers reread current state; payload detail belongs to THE-547. Monitoring notice types mirror WebhookEvent and include monitoring references; event_id identifies that same committed notice. Delivery status changes emit delivery.updated events only to the feed, never recursive webhooks.

`ChangePage`

Field	Type	Required	Description
`items`	array of `ChangeEvent`	yes
`next_cursor`	string	yes	Minimum length `1`.
`has_more`	boolean	yes

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/ChangeEvent'
  next_cursor:
    type: string
    minLength: 1
  has_more:
    type: boolean
required:
  - items
  - next_cursor
  - has_more

`ResolvedRelation`

Separate live view, not a mutation of the source Manifest. Unavailable covers missing, unready, withdrawn and inaccessible without distinguishing existence or revealing resolved target IDs.

Field	Type	Required	Description
`source_reference`	`RelationInput`	yes
`status`	string	yes	One of `available`, `unavailable`.
`target_record_id`	string
`target_version_id`	string

Further rules (conditional requirements or combinations) are in the full schema below.

Full schema

type: object
additionalProperties: false
required:
  - source_reference
  - status
properties:
  source_reference:
    $ref: '#/components/schemas/RelationInput'
  status:
    type: string
    enum:
      - available
      - unavailable
  target_record_id:
    type: string
  target_version_id:
    type: string
description: Separate live view, not a mutation of the source Manifest. Unavailable covers missing, unready, withdrawn and inaccessible without distinguishing existence or revealing resolved target IDs.
if:
  properties:
    status:
      const: available
then:
  required:
    - target_record_id
    - target_version_id
else:
  not:
    anyOf:
      - required:
          - target_record_id
      - required:
          - target_version_id

`ProcessingSummary`

Live read view, not a Receipt lifecycle or public workflow identifier. blocked means an outstanding contribution needs intervention; diagnostics describe why. idle means no work currently pending, not a promise of final enrichment. Phase is omitted when idle; required and optional progress do not override Version Availability.

Field	Type	Required	Description
`state`	string	yes	One of `queued`, `running`, `retrying`, `blocked`, `idle`.
`phase`	string		One of `materialization`, `baseline`, `enrichment`.
`message`	string

Full schema

type: object
additionalProperties: false
required:
  - state
properties:
  state:
    type: string
    enum:
      - queued
      - running
      - retrying
      - blocked
      - idle
  phase:
    type: string
    enum:
      - materialization
      - baseline
      - enrichment
  message:
    type: string
description: Live read view, not a Receipt lifecycle or public workflow identifier. blocked means an outstanding contribution needs intervention; diagnostics describe why. idle means no work currently pending, not a promise of final enrichment. Phase is omitted when idle; required and optional progress do not override Version Availability.

`SavedQueryDefinition`

Immutable query definition. Expression semantics belong to the evaluator plugin; no core keyword or semantic threshold is implied. All Corpora belong to the authorized Organization.

Field	Type	Required	Description
`corpus_ids`	array of string	yes	At least `1` items. Items are unique. Each item: Minimum length `1`.
`expression`	object	yes
`retrieval_profile`	string	yes	A search profile the deployment answers (listSearchProfiles), recorded as sent; balanced, the deprecated name of default, is accepted through engine 0.1.x. Another profile is 422 unsupported_profile. The profile is checked only when a definition is written, so a Version keeps its profile and keeps evaluating after the profile stops being served. Minimum length `1`.
`temporal_policy`	string	yes	One of `from_activation`.

Full schema

type: object
additionalProperties: false
properties:
  corpus_ids:
    type: array
    items:
      type: string
      minLength: 1
    minItems: 1
    uniqueItems: true
  expression:
    type: object
    additionalProperties: true
  retrieval_profile:
    type: string
    minLength: 1
    description: A search profile the deployment answers (listSearchProfiles), recorded as sent; balanced, the deprecated name of default, is accepted through engine 0.1.x. Another profile is 422 unsupported_profile. The profile is checked only when a definition is written, so a Version keeps its profile and keeps evaluating after the profile stops being served.
  temporal_policy:
    type: string
    enum:
      - from_activation
required:
  - corpus_ids
  - expression
  - retrieval_profile
  - temporal_policy
description: Immutable query definition. Expression semantics belong to the evaluator plugin; no core keyword or semantic threshold is implied. All Corpora belong to the authorized Organization.

`SavedQueryCreate`

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`name`	string	yes	Minimum length `1`.
`definition`	`SavedQueryDefinition`	yes

Example saved_query_create:

{
  "idempotency_key": "create-query-1",
  "name": "Example query",
  "definition": {
    "corpus_ids": [
      "corpus_news"
    ],
    "expression": {
      "fixture": "positive"
    },
    "retrieval_profile": "default",
    "temporal_policy": "from_activation"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
  definition:
    $ref: '#/components/schemas/SavedQueryDefinition'
required:
  - idempotency_key
  - name
  - definition

`SavedQueryVersionCreate`

New immutable definition of an existing Saved Query. The name is unchanged (rename changes it).

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`definition`	`SavedQueryDefinition`	yes

Example saved_query_version_create:

{
  "idempotency_key": "edit-query-1",
  "definition": {
    "corpus_ids": [
      "corpus_news"
    ],
    "expression": {
      "fixture": "negative"
    },
    "retrieval_profile": "default",
    "temporal_policy": "from_activation"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  definition:
    $ref: '#/components/schemas/SavedQueryDefinition'
required:
  - idempotency_key
  - definition
description: New immutable definition of an existing Saved Query. The name is unchanged (rename changes it).

`SavedQueryVersion`

Field	Type	Required	Description
`saved_query_id`	string	yes	Minimum length `1`.
`version_id`	string	yes	Minimum length `1`.
`definition`	`SavedQueryDefinition`	yes

Full schema

type: object
additionalProperties: false
properties:
  saved_query_id:
    type: string
    minLength: 1
  version_id:
    type: string
    minLength: 1
  definition:
    $ref: '#/components/schemas/SavedQueryDefinition'
required:
  - saved_query_id
  - version_id
  - definition

`SavedQuery`

Field	Type	Required	Description
`saved_query_id`	string	yes	Minimum length `1`.
`name`	string	yes	Minimum length `1`.
`deleted`	boolean	yes	Logically deleted; the Saved Query and its Versions stay readable.
`current_version`	`SavedQueryVersion`	yes

Example saved_query:

{
  "saved_query_id": "query_1",
  "name": "Example query",
  "deleted": false,
  "current_version": {
    "saved_query_id": "query_1",
    "version_id": "query_version_1",
    "definition": {
      "corpus_ids": [
        "corpus_news"
      ],
      "expression": {
        "fixture": "positive"
      },
      "retrieval_profile": "default",
      "temporal_policy": "from_activation"
    }
  }
}

Full schema

type: object
additionalProperties: false
properties:
  saved_query_id:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
  deleted:
    type: boolean
    description: Logically deleted; the Saved Query and its Versions stay readable.
  current_version:
    $ref: '#/components/schemas/SavedQueryVersion'
required:
  - saved_query_id
  - name
  - deleted
  - current_version

`EvaluatorConfig`

Pins an installed evaluator by plugin id and version, and its configuration. Evaluators are the subscription Contributions of the plugins pinned at startup (Plugin Protocol v0); test deployments may also install the deterministic fixture quivr.fixture@1. The configuration must satisfy the evaluator’s declared configuration schema.

Field	Type	Required	Description
`plugin_id`	string	yes	Minimum length `1`.
`version`	string	yes	Minimum length `1`.
`configuration`	object	yes

Full schema

type: object
additionalProperties: false
properties:
  plugin_id:
    type: string
    minLength: 1
  version:
    type: string
    minLength: 1
  configuration:
    type: object
    additionalProperties: true
required:
  - plugin_id
  - version
  - configuration
description: Pins an installed evaluator by plugin id and version, and its configuration. Evaluators are the subscription Contributions of the plugins pinned at startup (Plugin Protocol v0); test deployments may also install the deterministic fixture quivr.fixture@1. The configuration must satisfy the evaluator's declared configuration schema.

`SubscriptionCreate`

Create enabled from-now Subscription. An optional owner makes it the Subscription of one end user of the client application; without one it is global to the Organization. The owner is fixed for the Subscription’s life and part of the idempotent request. One deployment-configured destination per version; destination belongs to this Organization. URL and signing key are provisioned outside this API and not returned. No inline secret or dynamic destination registry in the tracer.

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`name`	string	yes	Minimum length `1`.
`saved_query_id`	string	yes	Minimum length `1`.
`saved_query_version_id`	string	yes	Minimum length `1`.
`evaluator`	`EvaluatorConfig`	yes
`destination_id`	string	yes	Minimum length `1`.
`owner`	`SubscriptionOwner`

Example subscription_create:

{
  "idempotency_key": "create-subscription-1",
  "name": "Example subscription",
  "saved_query_id": "query_1",
  "saved_query_version_id": "query_version_1",
  "evaluator": {
    "plugin_id": "fixture-evaluator",
    "version": "1",
    "configuration": {
      "scenario": "positive",
      "parameters": {
        "sample": true
      }
    }
  },
  "destination_id": "fixture_webhook"
}

Example owned_subscription_create:

{
  "idempotency_key": "create-subscription-user-123",
  "name": "Alert for one end user",
  "saved_query_id": "query_1",
  "saved_query_version_id": "query_version_1",
  "evaluator": {
    "plugin_id": "fixture-evaluator",
    "version": "1",
    "configuration": {
      "scenario": "positive",
      "parameters": {
        "sample": true
      }
    }
  },
  "destination_id": "fixture_webhook",
  "owner": "user-123"
}

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
  saved_query_id:
    type: string
    minLength: 1
  saved_query_version_id:
    type: string
    minLength: 1
  evaluator:
    $ref: '#/components/schemas/EvaluatorConfig'
  destination_id:
    type: string
    minLength: 1
  owner:
    $ref: '#/components/schemas/SubscriptionOwner'
required:
  - idempotency_key
  - name
  - saved_query_id
  - saved_query_version_id
  - evaluator
  - destination_id
description: Create enabled from-now Subscription. An optional owner makes it the Subscription of one end user of the client application; without one it is global to the Organization. The owner is fixed for the Subscription's life and part of the idempotent request. One deployment-configured destination per version; destination belongs to this Organization. URL and signing key are provisioned outside this API and not returned. No inline secret or dynamic destination registry in the tracer.

`SubscriptionVersionCreate`

New immutable configuration of an existing Subscription. The Saved Query and name are unchanged (rename changes the name); saved_query_version_id is the current Version of that Saved Query.

Field	Type	Required	Description
`idempotency_key`	string	yes	Minimum length `1`.
`saved_query_version_id`	string	yes	Minimum length `1`.
`evaluator`	`EvaluatorConfig`	yes
`destination_id`	string	yes	Minimum length `1`.

Example subscription_version_create:

{
  "idempotency_key": "edit-subscription-1",
  "saved_query_version_id": "query_version_2",
  "evaluator": {
    "plugin_id": "fixture-evaluator",
    "version": "1",
    "configuration": {
      "scenario": "negative"
    }
  },
  "destination_id": "fixture_webhook"
}

Full schema

type: object
additionalProperties: false
properties:
  idempotency_key:
    type: string
    minLength: 1
  saved_query_version_id:
    type: string
    minLength: 1
  evaluator:
    $ref: '#/components/schemas/EvaluatorConfig'
  destination_id:
    type: string
    minLength: 1
required:
  - idempotency_key
  - saved_query_version_id
  - evaluator
  - destination_id
description: New immutable configuration of an existing Subscription. The Saved Query and name are unchanged (rename changes the name); saved_query_version_id is the current Version of that Saved Query.

`SubscriptionVersion`

Immutable Subscription configuration. Every Version keeps the Subscription’s owner, absent for a global Subscription.

Field	Type	Required	Description
`subscription_id`	string	yes	Minimum length `1`.
`version_id`	string	yes	Minimum length `1`.
`saved_query_id`	string	yes	Minimum length `1`.
`saved_query_version_id`	string	yes	Minimum length `1`.
`evaluator`	`EvaluatorConfig`	yes
`destination_id`	string	yes	Minimum length `1`.
`owner`	`SubscriptionOwner`

Full schema

type: object
additionalProperties: false
properties:
  subscription_id:
    type: string
    minLength: 1
  version_id:
    type: string
    minLength: 1
  saved_query_id:
    type: string
    minLength: 1
  saved_query_version_id:
    type: string
    minLength: 1
  evaluator:
    $ref: '#/components/schemas/EvaluatorConfig'
  destination_id:
    type: string
    minLength: 1
  owner:
    $ref: '#/components/schemas/SubscriptionOwner'
required:
  - subscription_id
  - version_id
  - saved_query_id
  - saved_query_version_id
  - evaluator
  - destination_id
description: Immutable Subscription configuration. Every Version keeps the Subscription's owner, absent for a global Subscription.

`Subscription`

Absent owner means a global, organization-wide Subscription.

Field	Type	Required	Description
`subscription_id`	string	yes	Minimum length `1`.
`name`	string	yes	Minimum length `1`.
`enabled`	boolean	yes
`deleted`	boolean	yes	Logically deleted for good; a deleted Subscription is also disabled and stays readable with its Versions, Matches and Deliveries.
`current_version`	`SubscriptionVersion`	yes
`owner`	`SubscriptionOwner`

Example subscription:

{
  "subscription_id": "subscription_1",
  "name": "Example subscription",
  "enabled": true,
  "deleted": false,
  "current_version": {
    "subscription_id": "subscription_1",
    "version_id": "subscription_version_1",
    "saved_query_id": "query_1",
    "saved_query_version_id": "query_version_1",
    "evaluator": {
      "plugin_id": "fixture-evaluator",
      "version": "1",
      "configuration": {
        "scenario": "positive",
        "parameters": {
          "sample": true
        }
      }
    },
    "destination_id": "fixture_webhook"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  subscription_id:
    type: string
    minLength: 1
  name:
    type: string
    minLength: 1
  enabled:
    type: boolean
  deleted:
    type: boolean
    description: Logically deleted for good; a deleted Subscription is also disabled and stays readable with its Versions, Matches and Deliveries.
  current_version:
    $ref: '#/components/schemas/SubscriptionVersion'
  owner:
    $ref: '#/components/schemas/SubscriptionOwner'
required:
  - subscription_id
  - name
  - enabled
  - deleted
  - current_version
description: Absent owner means a global, organization-wide Subscription.

`SubscriptionOwner`

Subscription Owner, an opaque end-user reference defined by the client application (for example user-123). Quivr stores, filters and echoes it without interpreting it. At most 128 characters without control characters; none is reserved for the listing filter (422 invalid_owner). Type: string. Minimum length 1. Maximum length 128.

Full schema

type: string
minLength: 1
maxLength: 128
description: Subscription Owner, an opaque end-user reference defined by the client application (for example user-123). Quivr stores, filters and echoes it without interpreting it. At most 128 characters without control characters; none is reserved for the listing filter (422 invalid_owner).

`SubscriptionPage`

Field	Type	Required	Description
`items`	array of `Subscription`	yes
`next_page_cursor`	string		Minimum length `1`.

Example owned_subscription_page:

{
  "items": [
    {
      "subscription_id": "subscription_2",
      "name": "Alert for one end user",
      "enabled": true,
      "deleted": false,
      "current_version": {
        "subscription_id": "subscription_2",
        "version_id": "subscription_version_2",
        "saved_query_id": "query_1",
        "saved_query_version_id": "query_version_1",
        "evaluator": {
          "plugin_id": "fixture-evaluator",
          "version": "1",
          "configuration": {
            "scenario": "positive",
            "parameters": {
              "sample": true
            }
          }
        },
        "destination_id": "fixture_webhook",
        "owner": "user-123"
      },
      "owner": "user-123"
    }
  ],
  "next_page_cursor": "opaque_page_cursor"
}

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/Subscription'
  next_page_cursor:
    type: string
    minLength: 1
required:
  - items

`SubscriptionPreviewRequest`

A proposed Subscription to preview. Give either definition, an inline Saved Query definition, or saved_query_id with saved_query_version_id, an existing Saved Query Version; not both.

Field	Type	Required	Description
`definition`	`SavedQueryDefinition`
`saved_query_id`	string		Minimum length `1`.
`saved_query_version_id`	string		Minimum length `1`.
`evaluator`	`EvaluatorConfig`	yes
`limit`	integer		The most Record Versions to judge, newest first. Each one costs an evaluator call. Default `20`. Minimum `1`. Maximum `50`.
`accepted_after`	string (date-time)		Judge only revisions accepted after this instant.

Full schema

type: object
additionalProperties: false
properties:
  definition:
    $ref: '#/components/schemas/SavedQueryDefinition'
  saved_query_id:
    type: string
    minLength: 1
  saved_query_version_id:
    type: string
    minLength: 1
  evaluator:
    $ref: '#/components/schemas/EvaluatorConfig'
  limit:
    type: integer
    minimum: 1
    maximum: 50
    default: 20
    description: The most Record Versions to judge, newest first. Each one costs an evaluator call.
  accepted_after:
    type: string
    format: date-time
    description: Judge only revisions accepted after this instant.
required:
  - evaluator
description: A proposed Subscription to preview. Give either definition, an inline Saved Query definition, or saved_query_id with saved_query_version_id, an existing Saved Query Version; not both.

`SubscriptionPreviewMatch`

A Record Version the proposed Subscription would have matched, with the evidence a Match would carry. It is not a Match and is not stored.

Field	Type	Required	Description
`corpus_id`	string	yes	Minimum length `1`.
`record_id`	string	yes	Minimum length `1`.
`record_version_id`	string	yes	Minimum length `1`.
`accepted_at`	string (date-time)	yes
`evidence`	`MatchEvidence`	yes

Full schema

type: object
additionalProperties: false
properties:
  corpus_id:
    type: string
    minLength: 1
  record_id:
    type: string
    minLength: 1
  record_version_id:
    type: string
    minLength: 1
  accepted_at:
    type: string
    format: date-time
  evidence:
    $ref: '#/components/schemas/MatchEvidence'
required:
  - corpus_id
  - record_id
  - record_version_id
  - accepted_at
  - evidence
description: A Record Version the proposed Subscription would have matched, with the evidence a Match would carry. It is not a Match and is not stored.

`SubscriptionPreview`

What a proposed Subscription would have matched among recent Record Versions.

Field	Type	Required	Description
`evaluated`	integer	yes	Record Versions the evaluator decided. Minimum `0`.
`matched`	integer	yes	Minimum `0`.
`not_ready`	integer	yes	Record Versions the evaluator could not decide yet (for example before enrichment). Minimum `0`.
`complete`	boolean	yes	False when the time budget ran out before every listed Record Version was decided.
`oldest_accepted_at`	string (date-time)		When the oldest decided Record Version was accepted; absent when none was decided.
`matches`	array of `SubscriptionPreviewMatch`	yes	Most recently accepted first. At most `50` items.

Full schema

type: object
additionalProperties: false
properties:
  evaluated:
    type: integer
    minimum: 0
    description: Record Versions the evaluator decided.
  matched:
    type: integer
    minimum: 0
  not_ready:
    type: integer
    minimum: 0
    description: Record Versions the evaluator could not decide yet (for example before enrichment).
  complete:
    type: boolean
    description: False when the time budget ran out before every listed Record Version was decided.
  oldest_accepted_at:
    type: string
    format: date-time
    description: When the oldest decided Record Version was accepted; absent when none was decided.
  matches:
    type: array
    maxItems: 50
    items:
      $ref: '#/components/schemas/SubscriptionPreviewMatch'
    description: Most recently accepted first.
required:
  - evaluated
  - matched
  - not_ready
  - complete
  - matches
description: What a proposed Subscription would have matched among recent Record Versions.

`MatchEvidence`

Immutable evidence for a positive result, including evaluator version/configuration. Details are plugin-defined, bounded to 16 KiB and schema-validated by its adapter; core checks referenced Parts. Access is rechecked on reads.

Field	Type	Required	Description
`evaluator`	`EvaluatorConfig`	yes
`explanation`	string	yes	Maximum length `4096`.
`part_keys`	array of string		At most `100` items. Each item: Minimum length `1`.
`details`	object

Full schema

type: object
additionalProperties: false
properties:
  evaluator:
    $ref: '#/components/schemas/EvaluatorConfig'
  explanation:
    type: string
    maxLength: 4096
  part_keys:
    type: array
    items:
      type: string
      minLength: 1
    maxItems: 100
  details:
    type: object
    additionalProperties: true
required:
  - evaluator
  - explanation
description: Immutable evidence for a positive result, including evaluator version/configuration. Details are plugin-defined, bounded to 16 KiB and schema-validated by its adapter; core checks referenced Parts. Access is rechecked on reads.

`Match`

Immutable positive historical determination, not a claim of current eligibility. Unique subscription-version/record-version. Correction/withdrawal notifications reference history; no Match is fabricated for negative decisions. owner is the Subscription’s owner, absent when global.

Field	Type	Required	Description
`match_id`	string	yes	Minimum length `1`.
`subscription_id`	string	yes	Minimum length `1`.
`subscription_version_id`	string	yes	Minimum length `1`.
`saved_query_id`	string	yes	Minimum length `1`.
`saved_query_version_id`	string	yes	Minimum length `1`.
`record_id`	string	yes	Minimum length `1`.
`record_version_id`	string	yes	Minimum length `1`.
`previous_match_id`	string		Minimum length `1`.
`owner`	`SubscriptionOwner`
`evidence`	`MatchEvidence`	yes

Example positive_match:

{
  "match_id": "match_1",
  "subscription_id": "subscription_1",
  "subscription_version_id": "subscription_version_1",
  "saved_query_id": "query_1",
  "saved_query_version_id": "query_version_1",
  "record_id": "record_1",
  "record_version_id": "version_1",
  "evidence": {
    "evaluator": {
      "plugin_id": "fixture-evaluator",
      "version": "1",
      "configuration": {
        "scenario": "positive",
        "parameters": {
          "sample": true
        }
      }
    },
    "explanation": "Résultat déterministe de la fixture",
    "part_keys": [
      "body"
    ],
    "details": {
      "fixture": true,
      "values": [
        1,
        false,
        null
      ]
    }
  }
}

Full schema

type: object
additionalProperties: false
properties:
  match_id:
    type: string
    minLength: 1
  subscription_id:
    type: string
    minLength: 1
  subscription_version_id:
    type: string
    minLength: 1
  saved_query_id:
    type: string
    minLength: 1
  saved_query_version_id:
    type: string
    minLength: 1
  record_id:
    type: string
    minLength: 1
  record_version_id:
    type: string
    minLength: 1
  previous_match_id:
    type: string
    minLength: 1
  owner:
    $ref: '#/components/schemas/SubscriptionOwner'
  evidence:
    $ref: '#/components/schemas/MatchEvidence'
required:
  - match_id
  - subscription_id
  - subscription_version_id
  - saved_query_id
  - saved_query_version_id
  - record_id
  - record_version_id
  - evidence
description: Immutable positive historical determination, not a claim of current eligibility. Unique subscription-version/record-version. Correction/withdrawal notifications reference history; no Match is fabricated for negative decisions. owner is the Subscription's owner, absent when global.

`MatchPage`

Field	Type	Required	Description
`items`	array of `Match`	yes
`next_page_cursor`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/Match'
  next_page_cursor:
    type: string
    minLength: 1
required:
  - items

`MonitoringReferences`

owner is the Subscription Owner, so a client routes the notice to its user; absent for a global Subscription and in notices committed before owners existed. match_id is the new Match for created/corrected, prior positive Match for no_longer_matches/withdrawn. record_version_id is the causal correction version for corrected/no_longer_matches, otherwise the matched version. References alone confer no access.

Field	Type	Required	Description
`match_id`	string	yes	Minimum length `1`.
`record_id`	string	yes	Minimum length `1`.
`record_version_id`	string	yes	Minimum length `1`.
`subscription_id`	string	yes	Minimum length `1`.
`subscription_version_id`	string	yes	Minimum length `1`.
`delivery_id`	string	yes	Minimum length `1`.
`previous_match_id`	string		Minimum length `1`.
`owner`	`SubscriptionOwner`

Full schema

type: object
additionalProperties: false
properties:
  match_id:
    type: string
    minLength: 1
  record_id:
    type: string
    minLength: 1
  record_version_id:
    type: string
    minLength: 1
  subscription_id:
    type: string
    minLength: 1
  subscription_version_id:
    type: string
    minLength: 1
  delivery_id:
    type: string
    minLength: 1
  previous_match_id:
    type: string
    minLength: 1
  owner:
    $ref: '#/components/schemas/SubscriptionOwner'
required:
  - match_id
  - record_id
  - record_version_id
  - subscription_id
  - subscription_version_id
  - delivery_id
description: owner is the Subscription Owner, so a client routes the notice to its user; absent for a global Subscription and in notices committed before owners existed. match_id is the new Match for created/corrected, prior positive Match for no_longer_matches/withdrawn. record_version_id is the causal correction version for corrected/no_longer_matches, otherwise the matched version. References alone confer no access.

`WebhookEvent`

Immutable reference-only notification. Retries preserve event_id and the exact stored body bytes; signing timestamp changes per attempt. No document content, excerpt, explanation, cursor or secret is embedded.

Field	Type	Required	Description
`event_id`	string	yes	Pattern `^[A-Za-z0-9_-]+$`.
`type`	string	yes	One of `match.created`, `match.corrected`, `match.no_longer_matches`, `match.withdrawn`.
`schema_version`	string	yes	One of `1`.
`occurred_at`	string (date-time)	yes
`references`	`MonitoringReferences`	yes

Example reference_webhook:

{
  "event_id": "event_match_1",
  "type": "match.created",
  "schema_version": "1",
  "occurred_at": "2026-09-14T12:00:00Z",
  "references": {
    "match_id": "match_1",
    "record_id": "record_1",
    "record_version_id": "version_1",
    "subscription_id": "subscription_1",
    "subscription_version_id": "subscription_version_1",
    "delivery_id": "delivery_1"
  }
}

Example owned_reference_webhook:

{
  "event_id": "event_match_2",
  "type": "match.created",
  "schema_version": "1",
  "occurred_at": "2026-09-14T12:00:00Z",
  "references": {
    "match_id": "match_2",
    "record_id": "record_1",
    "record_version_id": "version_1",
    "subscription_id": "subscription_2",
    "subscription_version_id": "subscription_version_2",
    "delivery_id": "delivery_2",
    "owner": "user-123"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  event_id:
    type: string
    pattern: ^[A-Za-z0-9_-]+$
  type:
    type: string
    enum:
      - match.created
      - match.corrected
      - match.no_longer_matches
      - match.withdrawn
  schema_version:
    type: string
    enum:
      - '1'
  occurred_at:
    type: string
    format: date-time
  references:
    $ref: '#/components/schemas/MonitoringReferences'
required:
  - event_id
  - type
  - schema_version
  - occurred_at
  - references
description: Immutable reference-only notification. Retries preserve event_id and the exact stored body bytes; signing timestamp changes per attempt. No document content, excerpt, explanation, cursor or secret is embedded.

`DeliveryAdmission`

Current derived admission view, separate from durable Delivery state. A disallowed pending Delivery makes no new network attempt; it does not become a new lifecycle state. destination_unavailable means its destination is no longer configured for the Organization. subscription_disabled lasts until a re-enable; subscription_deleted is permanent. record_withdrawn refuses match.created, match.corrected and match.no_longer_matches; match.withdrawn is admitted for a withdrawn Record. superseded refuses an undelivered match.created or match.corrected once a later match.corrected or match.no_longer_matches exists for the same Subscription and Record, and an undelivered match.no_longer_matches once a later match.corrected exists; match.withdrawn is never superseded.

Field	Type	Required	Description
`allowed`	boolean	yes
`reason`	string		One of `subscription_disabled`, `subscription_deleted`, `record_withdrawn`, `superseded`, `access_denied`, `destination_unavailable`, `terminal`.

Full schema

type: object
additionalProperties: false
properties:
  allowed:
    type: boolean
  reason:
    type: string
    enum:
      - subscription_disabled
      - subscription_deleted
      - record_withdrawn
      - superseded
      - access_denied
      - destination_unavailable
      - terminal
required:
  - allowed
description: Current derived admission view, separate from durable Delivery state. A disallowed pending Delivery makes no new network attempt; it does not become a new lifecycle state. destination_unavailable means its destination is no longer configured for the Organization. subscription_disabled lasts until a re-enable; subscription_deleted is permanent. record_withdrawn refuses match.created, match.corrected and match.no_longer_matches; match.withdrawn is admitted for a withdrawn Record. superseded refuses an undelivered match.created or match.corrected once a later match.corrected or match.no_longer_matches exists for the same Subscription and Record, and an undelivered match.no_longer_matches once a later match.corrected exists; match.withdrawn is never superseded.

`Delivery`

Field	Type	Required	Description
`delivery_id`	string	yes	Minimum length `1`.
`match_id`	string	yes	Minimum length `1`.
`destination_id`	string	yes	Minimum length `1`.
`state`	string	yes	One of `pending`, `delivering`, `delivered`, `exhausted`.
`event`	`WebhookEvent`	yes
`attempt_count`	integer	yes	Minimum `0`.
`admission`	`DeliveryAdmission`	yes
`last_error`	`Error`
`next_attempt_at`	string (date-time)		When the next automatic attempt becomes eligible. Present only while the Delivery is pending and admission is allowed; a retry waits with jittered exponential backoff (or a valid Retry-After on 429/503), never beyond the delivery window.

Example delivery:

{
  "delivery_id": "delivery_1",
  "match_id": "match_1",
  "destination_id": "fixture_webhook",
  "state": "pending",
  "event": {
    "event_id": "event_match_1",
    "type": "match.created",
    "schema_version": "1",
    "occurred_at": "2026-09-14T12:00:00Z",
    "references": {
      "match_id": "match_1",
      "record_id": "record_1",
      "record_version_id": "version_1",
      "subscription_id": "subscription_1",
      "subscription_version_id": "subscription_version_1",
      "delivery_id": "delivery_1"
    }
  },
  "attempt_count": 1,
  "admission": {
    "allowed": false,
    "reason": "subscription_disabled"
  }
}

Full schema

type: object
additionalProperties: false
properties:
  delivery_id:
    type: string
    minLength: 1
  match_id:
    type: string
    minLength: 1
  destination_id:
    type: string
    minLength: 1
  state:
    type: string
    enum:
      - pending
      - delivering
      - delivered
      - exhausted
  event:
    $ref: '#/components/schemas/WebhookEvent'
  attempt_count:
    type: integer
    minimum: 0
  admission:
    $ref: '#/components/schemas/DeliveryAdmission'
  last_error:
    $ref: '#/components/schemas/Error'
  next_attempt_at:
    type: string
    format: date-time
    description: When the next automatic attempt becomes eligible. Present only while the Delivery is pending and admission is allowed; a retry waits with jittered exponential backoff (or a valid Retry-After on 429/503), never beyond the delivery window.
required:
  - delivery_id
  - match_id
  - destination_id
  - state
  - event
  - attempt_count
  - admission

`DeliveryAttempt`

Read view of append-only admission/outcome facts. Unknown network result can be retried with the same event ID; no response body, signature or signing key is exposed.

Field	Type	Required	Description
`attempt_id`	string	yes	Minimum length `1`.
`delivery_id`	string	yes	Minimum length `1`.
`number`	integer	yes	Minimum `1`.
`outcome`	string	yes	One of `in_flight`, `acknowledged`, `retryable_error`, `permanent_error`, `unknown`.
`http_status`	integer		Minimum `100`. Maximum `599`.
`error`	`Error`

Full schema

type: object
additionalProperties: false
properties:
  attempt_id:
    type: string
    minLength: 1
  delivery_id:
    type: string
    minLength: 1
  number:
    type: integer
    minimum: 1
  outcome:
    type: string
    enum:
      - in_flight
      - acknowledged
      - retryable_error
      - permanent_error
      - unknown
  http_status:
    type: integer
    minimum: 100
    maximum: 599
  error:
    $ref: '#/components/schemas/Error'
required:
  - attempt_id
  - delivery_id
  - number
  - outcome
description: Read view of append-only admission/outcome facts. Unknown network result can be retried with the same event ID; no response body, signature or signing key is exposed.

`DeliveryAttemptPage`

Field	Type	Required	Description
`items`	array of `DeliveryAttempt`	yes
`next_page_cursor`	string		Minimum length `1`.

Example attempt_page:

{
  "items": [
    {
      "attempt_id": "attempt_1",
      "delivery_id": "delivery_1",
      "number": 1,
      "outcome": "retryable_error",
      "http_status": 503,
      "error": {
        "code": "receiver_unavailable",
        "message": "HTTP 503",
        "retryable": true
      }
    }
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/DeliveryAttempt'
  next_page_cursor:
    type: string
    minLength: 1
required:
  - items

`SearchRequest`

Text-only top-k query. Resolve all Corpora in the authenticated Organization and require read/search permission for every requested Corpus before querying. Never silently drop an unauthorized Corpus. Unknown/unsupported profile or mode returns 422; a dependency outage is an error, not an empty successful result. Query token limits are checked against the resolved profile; no silent truncation. An optional filter narrows candidates inside the engine query, before ranking and the limit, in every mode. Other metadata filters and pagination are outside this surface.

Field	Type	Required	Description
`query`	string	yes	At most 8192 code points on the wire. A semantic or hybrid query is also limited by the owner of the searched vector space (the first-party core.ingest plugin accepts at most 256 tokens of its model’s tokenizer); a longer query is refused with 422 query_too_long, whose message names the limit, never truncated. Minimum length `1`. Maximum length `8192`.
`corpus_ids`	array of string	yes	At least `1` items. At most `16` items. Items are unique. Each item: Minimum length `1`.
`mode`	string		One of `lexical`, `semantic`, `hybrid`. Default `hybrid`.
`profile`	string		A search profile this deployment answers (listSearchProfiles). The built-in path answers default only; a pinned retrieval plugin answers the profiles it declares, default among them. balanced is a deprecated alias of default, accepted through engine 0.1.x and removed in engine 0.2.0. An unknown profile returns 422 unsupported_profile. Default `default`. Pattern `^[a-z][a-z0-9_]{0,31}$`.
`limit`	integer		Default `10`. Minimum `1`. Maximum `50`.
`filter`	`SearchFilter`

Example text_search:

{
  "query": "énergie solaire 🌞",
  "corpus_ids": [
    "corpus_news"
  ],
  "mode": "hybrid",
  "profile": "default",
  "limit": 10
}

Full schema

type: object
additionalProperties: false
properties:
  query:
    type: string
    minLength: 1
    maxLength: 8192
    description: At most 8192 code points on the wire. A semantic or hybrid query is also limited by the owner of the searched vector space (the first-party core.ingest plugin accepts at most 256 tokens of its model's tokenizer); a longer query is refused with 422 query_too_long, whose message names the limit, never truncated.
  corpus_ids:
    type: array
    items:
      type: string
      minLength: 1
    minItems: 1
    maxItems: 16
    uniqueItems: true
  mode:
    type: string
    enum:
      - lexical
      - semantic
      - hybrid
    default: hybrid
  profile:
    type: string
    pattern: ^[a-z][a-z0-9_]{0,31}$
    default: default
    description: A search profile this deployment answers (listSearchProfiles). The built-in path answers default only; a pinned retrieval plugin answers the profiles it declares, default among them. balanced is a deprecated alias of default, accepted through engine 0.1.x and removed in engine 0.2.0. An unknown profile returns 422 unsupported_profile.
  limit:
    type: integer
    minimum: 1
    maximum: 50
    default: 10
  filter:
    $ref: '#/components/schemas/SearchFilter'
required:
  - query
  - corpus_ids
description: Text-only top-k query. Resolve all Corpora in the authenticated Organization and require read/search permission for every requested Corpus before querying. Never silently drop an unauthorized Corpus. Unknown/unsupported profile or mode returns 422; a dependency outage is an error, not an empty successful result. Query token limits are checked against the resolved profile; no silent truncation. An optional filter narrows candidates inside the engine query, before ranking and the limit, in every mode. Other metadata filters and pagination are outside this surface.

Candidate filter applied before ranking. Every present condition must hold. A requested Corpus served by a Projection Generation built before source filtering existed returns 422 source_filter_unavailable; rebuild that Corpus once (rebuildCorpusProjection) to enable it. Unfiltered search is unaffected.

Field	Type	Required	Description
`source_namespaces`	array of string		Keep only Records whose Source Namespace is one of these values. Ranking and the limit apply within the filtered set, so a source’s best matches are returned even when other sources outrank them. At least `1` items. At most `50` items. Items are unique. Each item: Minimum length `1`. Maximum length `200`.

Full schema

type: object
additionalProperties: false
minProperties: 1
properties:
  source_namespaces:
    type: array
    items:
      type: string
      minLength: 1
      maxLength: 200
    minItems: 1
    maxItems: 50
    uniqueItems: true
    description: Keep only Records whose Source Namespace is one of these values. Ranking and the limit apply within the filtered set, so a source's best matches are returned even when other sources outrank them.
description: Candidate filter applied before ranking. Every present condition must hold. A requested Corpus served by a Projection Generation built before source filtering existed returns 422 source_filter_unavailable; rebuild that Corpus once (rebuildCorpusProjection) to enable it. Unfiltered search is unaffected.

`SearchProfile`

Resolved retrieval profile identity. Name is the profile that answered (default when the request named none or the deprecated balanced). Version identifies what ranked; the built-in path’s immutable profile version, or plugin:<plugin id>@<version>/<profile> for a retrieval plugin.

Field	Type	Required	Description
`name`	string	yes	Minimum length `1`.
`version`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  name:
    type: string
    minLength: 1
  version:
    type: string
    minLength: 1
required:
  - name
  - version
description: Resolved retrieval profile identity. Name is the profile that answered (default when the request named none or the deprecated balanced). Version identifies what ranked; the built-in path's immutable profile version, or plugin:<plugin id>@<version>/<profile> for a retrieval plugin.

`SearchProfileList`

Field	Type	Required	Description
`items`	array of `SearchProfileDescription`	yes	At least `1` items. At most `8` items.

Example search_profiles:

{
  "items": [
    {
      "name": "default",
      "description": "Keywords and vectors fused by rank.",
      "max_latency_ms": 500,
      "max_cost_cents": 0,
      "provider": {
        "kind": "plugin",
        "plugin_id": "example.fusion",
        "plugin_version": "0.1.0"
      }
    }
  ]
}

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/SearchProfileDescription'
    minItems: 1
    maxItems: 8
required:
  - items

`SearchProfileDescription`

Field	Type	Required	Description
`name`	string	yes	Minimum length `1`.
`description`	string
`max_latency_ms`	integer		Deadline of one search under this profile; absent for the built-in default. Minimum `1`.
`max_cost_cents`	number		Most a search may spend on paid calls; absent for the built-in default. Minimum `0`.
`provider`	object	yes
`provider.kind`	string	yes	One of `engine`, `plugin`.
`provider.plugin_id`	string		Minimum length `1`.
`provider.plugin_version`	string		Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  name:
    type: string
    minLength: 1
  description:
    type: string
  max_latency_ms:
    type: integer
    minimum: 1
    description: Deadline of one search under this profile; absent for the built-in default.
  max_cost_cents:
    type: number
    minimum: 0
    description: Most a search may spend on paid calls; absent for the built-in default.
  provider:
    type: object
    additionalProperties: false
    properties:
      kind:
        type: string
        enum:
          - engine
          - plugin
      plugin_id:
        type: string
        minLength: 1
      plugin_version:
        type: string
        minLength: 1
    required:
      - kind
required:
  - name
  - provider

`SearchUsage`

What a search answered by a retrieval plugin spent; rounds of the plugin, elapsed time, and the paid calls and cost the plugin reported.

Field	Type	Required	Description
`rounds`	integer	yes	Minimum `1`. Maximum `3`.
`elapsed_ms`	integer	yes	Minimum `0`.
`paid_calls`	integer	yes	Minimum `0`.
`cost_cents`	number	yes	Minimum `0`.

Full schema

type: object
additionalProperties: false
properties:
  rounds:
    type: integer
    minimum: 1
    maximum: 3
  elapsed_ms:
    type: integer
    minimum: 0
  paid_calls:
    type: integer
    minimum: 0
  cost_cents:
    type: number
    minimum: 0
required:
  - rounds
  - elapsed_ms
  - paid_calls
  - cost_cents
description: What a search answered by a retrieval plugin spent; rounds of the plugin, elapsed time, and the paid calls and cost the plugin reported.

`SearchExcerpt`

Exact canonical normalized Part text slice [start,end), using Unicode code points, not UTF-8 bytes or UTF-16 units. End must be >= start and end-start must equal the excerpt code-point length. Bounds are checked against the referenced immutable Part. No synthetic highlights or rewritten snippets.

Field	Type	Required	Description
`text`	string	yes	Maximum length `4096`.
`start`	integer	yes	Minimum `0`.
`end`	integer	yes	Minimum `0`.
`coordinate_system`	string	yes	One of `unicode_codepoint`.

Full schema

type: object
additionalProperties: false
properties:
  text:
    type: string
    maxLength: 4096
  start:
    type: integer
    minimum: 0
  end:
    type: integer
    minimum: 0
  coordinate_system:
    type: string
    enum:
      - unicode_codepoint
required:
  - text
  - start
  - end
  - coordinate_system
description: Exact canonical normalized Part text slice [start,end), using Unicode code points, not UTF-8 bytes or UTF-16 units. End must be >= start and end-start must equal the excerpt code-point length. Bounds are checked against the referenced immutable Part. No synthetic highlights or rewritten snippets.

`SearchHit`

One authorized segment hit. Rehydrate from canonical storage and recheck Organization/Corpus access, currentness, quarantine and Tombstone before returning. Rank is contiguous and one-based after hydration/filtering. Projection Generation, segmentation, segment and optional Embedding Artifact/Vector Space are logical durable IDs, not physical collection names or workflow IDs. Embedding references are omitted when that segment has lexical coverage only. They do not assert that the dense branch contributed to its rank. All hits inherit the response retrieval profile. Raw scores/explainScore stay internal.

Field	Type	Required	Description
`record_id`	string	yes	Minimum length `1`.
`version_id`	string	yes	Minimum length `1`.
`part_key`	string	yes	Minimum length `1`.
`segment_id`	string	yes	Minimum length `1`.
`segmentation_id`	string	yes	Minimum length `1`.
`projection_generation_id`	string	yes	Minimum length `1`.
`embedding_artifact_id`	string		Minimum length `1`.
`vector_space_id`	string		Minimum length `1`.
`rank`	integer	yes	Minimum `1`.
`excerpt`	`SearchExcerpt`	yes
`availability`	`Availability`	yes
`explanation`	string		Why the retrieval plugin ranked this hit here, when it says so. Minimum length `1`. Maximum length `1024`.

Further rules (conditional requirements or combinations) are in the full schema below.

Full schema

type: object
additionalProperties: false
properties:
  record_id:
    type: string
    minLength: 1
  version_id:
    type: string
    minLength: 1
  part_key:
    type: string
    minLength: 1
  segment_id:
    type: string
    minLength: 1
  segmentation_id:
    type: string
    minLength: 1
  projection_generation_id:
    type: string
    minLength: 1
  embedding_artifact_id:
    type: string
    minLength: 1
  vector_space_id:
    type: string
    minLength: 1
  rank:
    type: integer
    minimum: 1
  excerpt:
    $ref: '#/components/schemas/SearchExcerpt'
  availability:
    $ref: '#/components/schemas/Availability'
  explanation:
    type: string
    minLength: 1
    maxLength: 1024
    description: Why the retrieval plugin ranked this hit here, when it says so.
required:
  - record_id
  - version_id
  - part_key
  - segment_id
  - segmentation_id
  - projection_generation_id
  - rank
  - excerpt
  - availability
description: One authorized segment hit. Rehydrate from canonical storage and recheck Organization/Corpus access, currentness, quarantine and Tombstone before returning. Rank is contiguous and one-based after hydration/filtering. Projection Generation, segmentation, segment and optional Embedding Artifact/Vector Space are logical durable IDs, not physical collection names or workflow IDs. Embedding references are omitted when that segment has lexical coverage only. They do not assert that the dense branch contributed to its rank. All hits inherit the response retrieval profile. Raw scores/explainScore stay internal.
if:
  required:
    - embedding_artifact_id
then:
  required:
    - vector_space_id
else:
  not:
    required:
      - vector_space_id

`SearchResponse`

Bounded top-k results after canonical rechecks. May contain fewer hits than requested; no total count, completeness promise or stable pagination snapshot. Empty results still name the resolved profile.

Field	Type	Required	Description
`items`	array of `SearchHit`	yes	At most `50` items.
`retrieval_profile`	`SearchProfile`	yes
`usage`	`SearchUsage`

Example canonical_search_results:

{
  "items": [
    {
      "record_id": "record_1",
      "version_id": "version_1",
      "part_key": "body",
      "segment_id": "segment_1",
      "segmentation_id": "segmentation_1",
      "projection_generation_id": "generation_1",
      "embedding_artifact_id": "embedding_1",
      "vector_space_id": "vectorspace_1",
      "rank": 1,
      "excerpt": {
        "text": "énergie 🌞",
        "start": 3,
        "end": 12,
        "coordinate_system": "unicode_codepoint"
      },
      "availability": {
        "state": "retrieval_ready",
        "is_current": true,
        "searchable": true
      }
    }
  ],
  "retrieval_profile": {
    "name": "default",
    "version": "quivr.text.fixture.v1"
  }
}

Example lexical_search_without_embedding:

{
  "items": [
    {
      "record_id": "record_2",
      "version_id": "version_2",
      "part_key": "body",
      "segment_id": "segment_2",
      "segmentation_id": "segmentation_2",
      "projection_generation_id": "generation_1",
      "rank": 1,
      "excerpt": {
        "text": "lune",
        "start": 0,
        "end": 4,
        "coordinate_system": "unicode_codepoint"
      },
      "availability": {
        "state": "retrieval_ready",
        "is_current": true,
        "searchable": true
      }
    }
  ],
  "retrieval_profile": {
    "name": "default",
    "version": "quivr.text.fixture.v1"
  }
}

Example plugin_ranked_search_results:

{
  "items": [
    {
      "record_id": "record_1",
      "version_id": "version_1",
      "part_key": "body",
      "segment_id": "segment_1",
      "segmentation_id": "segmentation_1",
      "projection_generation_id": "generation_1",
      "rank": 1,
      "excerpt": {
        "text": "énergie 🌞",
        "start": 3,
        "end": 12,
        "coordinate_system": "unicode_codepoint"
      },
      "availability": {
        "state": "retrieval_ready",
        "is_current": true,
        "searchable": true
      },
      "explanation": "rank 1 by keywords, rank 2 by the served space"
    }
  ],
  "retrieval_profile": {
    "name": "deep",
    "version": "plugin:example.fusion@0.1.0/deep"
  },
  "usage": {
    "rounds": 2,
    "elapsed_ms": 84,
    "paid_calls": 0,
    "cost_cents": 0
  }
}

Full schema

type: object
additionalProperties: false
properties:
  items:
    type: array
    items:
      $ref: '#/components/schemas/SearchHit'
    maxItems: 50
  retrieval_profile:
    $ref: '#/components/schemas/SearchProfile'
  usage:
    $ref: '#/components/schemas/SearchUsage'
required:
  - items
  - retrieval_profile
description: Bounded top-k results after canonical rechecks. May contain fewer hits than requested; no total count, completeness promise or stable pagination snapshot. Empty results still name the resolved profile.

`ProjectionRebuildResult`

Logical generation activated for the requested Corpus. Opaque ID, never a physical search collection name.

Field	Type	Required	Description
`projection_generation_id`	string	yes	Minimum length `1`.

Full schema

type: object
additionalProperties: false
properties:
  projection_generation_id:
    type: string
    minLength: 1
required:
  - projection_generation_id
description: Logical generation activated for the requested Corpus. Opaque ID, never a physical search collection name.

​Authentication

​Endpoints

​Records

​POST /v0/records

​GET /v0/records

​POST /v0/records/batch

​POST /v0/records/withdrawals

​GET /v0/records/{record_id}

​GET /v0/records/{record_id}/versions/{version_id}

​Ingestion receipts

​GET /v0/ingestion-receipts/{receipt_id}

​Uploads

​POST /v0/uploads

​POST /v0/uploads/{upload_id}/confirm

​GET /v0/uploads/{upload_id}

​Blobs

​GET /v0/blobs/{blob_id}

​Operations

​GET /v0/operations/{operation_id}

​POST /v0/operations/{operation_id}/cancel

​POST /v0/operations/{operation_id}/rerun

​Corpora

​POST /v0/corpora

​GET /v0/corpora

​GET /v0/corpora/{corpus_id}

​PUT /v0/corpora/{corpus_id}/retrieval

​GET /v0/corpora/{corpus_id}/vector-spaces

​POST /v0/corpora/{corpus_id}/rebuilds

​Changes

​GET /v0/changes

​GET /v0/changes/stream

​Saved queries

​POST /v0/saved-queries

​GET /v0/saved-queries/{saved_query_id}

​GET /v0/saved-queries/{saved_query_id}/versions/{version_id}

​POST /v0/saved-queries/{saved_query_id}/versions

​POST /v0/saved-queries/{saved_query_id}/delete

​POST /v0/saved-queries/{saved_query_id}/rename

​Subscriptions

​GET /v0/subscriptions

​POST /v0/subscriptions

​GET /v0/subscriptions/{subscription_id}

​GET /v0/subscriptions/{subscription_id}/versions/{version_id}

​POST /v0/subscriptions/{subscription_id}/versions

​POST /v0/subscriptions/{subscription_id}/delete

​POST /v0/subscriptions/{subscription_id}/disable

​POST /v0/subscriptions/{subscription_id}/enable

​POST /v0/subscriptions/{subscription_id}/rename

​Subscription previews

​POST /v0/subscription-previews

​Matches

​GET /v0/matches

​GET /v0/matches/{match_id}

​Deliveries

​GET /v0/deliveries/{delivery_id}

​GET /v0/deliveries/{delivery_id}/attempts

​Connectors

​POST /v0/connectors

​GET /v0/connectors

​GET /v0/connectors/{connector_id}

​POST /v0/connectors/{connector_id}/disable

​PUT /v0/connectors/{connector_id}/credential

​PUT /v0/connectors/{connector_id}/schedule

​POST /v0/connectors/{connector_id}/runs

​Connector webhooks

​GET /v0/connector-webhooks/{connector_id}

​POST /v0/connector-webhooks/{connector_id}

​Connector kinds

​GET /v0/connector-kinds

​Admin

​GET /v0/admin/plugins

​GET /v0/admin/plugins/plan

​Search

​POST /v0/search

​GET /v0/search/profiles

​Webhooks

​monitoringNotification (POST)

​Schemas

​SourceIdentity

​Error

Authentication

Endpoints

Records

`POST /v0/records`

`GET /v0/records`

`POST /v0/records/batch`

`POST /v0/records/withdrawals`

`GET /v0/records/{record_id}`

`GET /v0/records/{record_id}/versions/{version_id}`

Ingestion receipts

`GET /v0/ingestion-receipts/{receipt_id}`

Uploads

`POST /v0/uploads`

`POST /v0/uploads/{upload_id}/confirm`

`GET /v0/uploads/{upload_id}`

Blobs

`GET /v0/blobs/{blob_id}`

Operations

`GET /v0/operations/{operation_id}`

`POST /v0/operations/{operation_id}/cancel`

`POST /v0/operations/{operation_id}/rerun`

Corpora

`POST /v0/corpora`

`GET /v0/corpora`

`GET /v0/corpora/{corpus_id}`

`PUT /v0/corpora/{corpus_id}/retrieval`

`GET /v0/corpora/{corpus_id}/vector-spaces`

`POST /v0/corpora/{corpus_id}/rebuilds`

Changes

`GET /v0/changes`

`GET /v0/changes/stream`

Saved queries

`POST /v0/saved-queries`

`GET /v0/saved-queries/{saved_query_id}`

`GET /v0/saved-queries/{saved_query_id}/versions/{version_id}`

`POST /v0/saved-queries/{saved_query_id}/versions`

`POST /v0/saved-queries/{saved_query_id}/delete`

`POST /v0/saved-queries/{saved_query_id}/rename`

Subscriptions

`GET /v0/subscriptions`

`POST /v0/subscriptions`

`GET /v0/subscriptions/{subscription_id}`

`GET /v0/subscriptions/{subscription_id}/versions/{version_id}`

`POST /v0/subscriptions/{subscription_id}/versions`

`POST /v0/subscriptions/{subscription_id}/delete`

`POST /v0/subscriptions/{subscription_id}/disable`

`POST /v0/subscriptions/{subscription_id}/enable`

`POST /v0/subscriptions/{subscription_id}/rename`

Subscription previews

`POST /v0/subscription-previews`

Matches

`GET /v0/matches`

`GET /v0/matches/{match_id}`

Deliveries

`GET /v0/deliveries/{delivery_id}`

`GET /v0/deliveries/{delivery_id}/attempts`

Connectors

`POST /v0/connectors`

`GET /v0/connectors`

`GET /v0/connectors/{connector_id}`

`POST /v0/connectors/{connector_id}/disable`

`PUT /v0/connectors/{connector_id}/credential`

`PUT /v0/connectors/{connector_id}/schedule`

`POST /v0/connectors/{connector_id}/runs`

Connector webhooks

`GET /v0/connector-webhooks/{connector_id}`

`POST /v0/connector-webhooks/{connector_id}`

Connector kinds

`GET /v0/connector-kinds`

Admin

`GET /v0/admin/plugins`

`GET /v0/admin/plugins/plan`

Search

`POST /v0/search`

`GET /v0/search/profiles`

Webhooks

`monitoringNotification` (POST)

Schemas

`SourceIdentity`

`Error`