---
title: "Preview subscription"
method: POST
path: "/v0/subscription-previews"
tags: ["Subscription previews"]
---

# Preview subscription

`POST /v0/subscription-previews`

## Request

- Base URL: `https://docs.quivr.thevibecompany.co` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.quivr.thevibecompany.co/v0/subscription-previews`
- Auth: HTTP bearer

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 four-second budget including preparation and storage reads; 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. A deadline during preparation or an earlier caller deadline returns retryable 504 preview_deadline_exceeded. A storage failure remains 503 storage_unavailable. Quivr applies no rate or cost rule; a layer above can limit who previews and how often.

## Request body

- 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.
  - `definition` 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.
    - `corpus_ids` string[], required
    - `expression` object, required
    - `retrieval_profile` string, required: A search profile the deployment answers (listSearchProfiles), recorded as sent; an unserved 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` 'from_activation', required
  - `saved_query_id` string
  - `saved_query_version_id` string
  - `evaluator` EvaluatorConfig, required: 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). The configuration must satisfy the evaluator's declared configuration schema.
    - `plugin_id` string, required
    - `version` string, required
    - `configuration` object, required
  - `limit` integer: The most Record Versions to judge, newest first. Each one costs an evaluator call.
  - `accepted_after` string, date-time: Judge only revisions accepted after this instant.

## Response `200`

Successful response

- SubscriptionPreview: What a proposed Subscription would have matched among recent Record Versions.
  - `evaluated` integer, required: Record Versions the evaluator decided.
  - `matched` integer, required
  - `not_ready` integer, required: Record Versions the evaluator could not decide yet (for example before enrichment).
  - `complete` boolean, required: 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` SubscriptionPreviewMatch[], required: Most recently accepted first.
    - `corpus_id` string, required
    - `record_id` string, required
    - `record_version_id` string, required
    - `accepted_at` string, date-time, required
    - `evidence` MatchEvidence, required: Immutable evidence for a positive result, including evaluator version/configuration. History retention may expire the entire evidence payload; historical reads then return 410 evidence_expired rather than a successful response with modified evidence. Details are plugin-defined, bounded to 16 KiB and schema-validated by its adapter; core checks referenced Parts. Access is rechecked on reads.
      - `evaluator` EvaluatorConfig, required: 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). The configuration must satisfy the evaluator's declared configuration schema.
        - `plugin_id` string, required
        - `version` string, required
        - `configuration` object, required
      - `explanation` string, required
      - `part_keys` string[]
      - `details` object

## Other responses

- `default`: Structured error. Existing /v0 authentication and scope semantics apply.

---

[API](https://skmtc.dev/thevibecompany/apis/quivr-http-api.md) - [All operations](https://skmtc.dev/thevibecompany/apis/quivr-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thevibecompany/apis/quivr-http-api/revisions/4f4e30ba8f4e?raw)