> ## Documentation Index > Fetch the complete documentation index at: https://docs.quivr.thevibecompany.co/llms.txt > Use this file to discover all available pages before exploring further. # Preview subscription > 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. ## OpenAPI ````yaml /openapi.yaml post /v0/subscription-previews openapi: 3.1.0 info: title: Quivr V2 public text foundation contract version: 0.0.0-draft description: >- 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. servers: [] security: - ApiKey: [] paths: /v0/subscription-previews: post: tags: - Subscription previews summary: Preview subscription description: >- 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. operationId: previewSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscriptionPreviewRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SubscriptionPreview' default: description: >- Structured error. Existing /v0 authentication and scope semantics apply. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SubscriptionPreviewRequest: 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. SubscriptionPreview: 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. Error: 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 SavedQueryDefinition: 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. EvaluatorConfig: 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. SubscriptionPreviewMatch: 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. MatchEvidence: 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. securitySchemes: ApiKey: type: http scheme: bearer description: >- API key, not necessarily a JWT. Server derives Organization, permitted actions and Corpus scope; every resource access is authorized. ````