---
title: "Rollback pipeline plan"
method: POST
path: "/v0/admin/plugins/plan/rollback"
tags: ["Admin"]
---

# Rollback pipeline plan

`POST /v0/admin/plugins/plan/rollback`

## 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/admin/plugins/plan/rollback`
- Auth: HTTP bearer

Restore an earlier immutable Pipeline Plan through a background Operation. plan_id defaults to the plan the active one replaced. Returning registrations must answer discovery with their exact manifest digest. Coverage gaps do not prevent rollback; affected records retain their outgoing owner and space until background recovery completes the returning projection. pinned_work chooses drain or stop for outgoing work; pinned Subscription Versions keep their evaluators. Follow Location; admin.plan_id names the new rollback plan. Requires plugins:admin.

## Request body

- PipelinePlanRollbackRequest
  - `idempotency_key` string, required
  - `plan_id` string: The plan whose roles become active again; absent returns to the plan the active one replaced (its previous_plan_id).
  - `pinned_work` 'drain' | 'stop': What happens to work pinned to a plan naming a plugin version the rollback takes out. drain lets it finish on that version, which stays draining meanwhile. stop keeps it from calling that version again once each process follows the new plan (within plugin_plan_poll). Its next call fails instead. The processing of a Version then stops with the diagnostic pinned_plan_stopped, with the outcome of pinned_plugin_unavailable, and a rebuild fails with that code. A connector run fails as when its plugin is unavailable, and its next run uses the active plan.

## Response `202`

Accepted background Operation.

- 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, retrieval_configuration and backfill Operations require corpus_id; when succeeded they require result naming the activated logical generation, or for a backfill the generation it filled. A backfill also carries backfill, and its counters versions_in_scope, versions_done, versions_skipped (with skipped_<reason>) and segments. A quarantine_reprocess carries corpus_id and quarantine_reprocess, and its counters versions_in_scope, versions_recovered, versions_quarantined and versions_skipped (with skipped_<reason>); it has no result. Only a backfill and a quarantine_reprocess can be paused. vector_space_promotion, plugin_activation and plugin_rollback carry admin, with no corpus_id. Their counters records_scanned, versions_missing and segments_missing describe the preflight; required_missing excludes gaps retained from an earlier rollback. Success publishes routing; rollback recovery continues in the background after success.
  - `operation_id` string, required
  - `kind` string, required
  - `state` 'queued' | 'running' | 'paused' | 'succeeded' | 'failed' | 'cancel_requested' | 'canceled', required
  - `progress` number: Approximate fraction, omitted when unknown.
  - `counters` object, required
  - `errors` Error[], required
    - `request_id` string: Bounded caller X-Request-ID, or an engine-generated correlation ID.
    - `trace_id` string: W3C trace ID when a trace context is present.
    - `span_id` string: W3C span ID of the API handler when a trace context is present.
    - `code` string, required
    - `message` string, required
    - `retryable` boolean, required
    - `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).
    - `resync_url` string, uri-reference
  - `previous_operation_id` string
  - `corpus_id` string
  - `result` ProjectionRebuildResult: Logical generation activated for the requested Corpus. Opaque ID, never a physical search collection name.
    - `projection_generation_id` string, required
  - `admin` OperationAdmin: Routing command target and successful cutover result. Administrative Operations have no corpus_id and require plugins:admin to follow. Their kinds are vector_space_promotion, plugin_activation and plugin_rollback.
    - `target` string
    - `plan_id` string
    - `previous_plan_id` string
    - `served_space_id` string
    - `previous_space_id` string
  - `backfill` OperationBackfill: What a backfill fills and how far it got.
    - `registration_id` string, required
    - `spaces` string[], required
    - `accepted_after` string, date-time
    - `accepted_before` string, date-time
    - `plan_id` string: The Pipeline Plan the backfill is pinned to, once it started.
    - `checkpoint` string: The last Version id it finished; it resumes after it, in Version id order.
    - `estimate` BackfillEstimate, required
      - `registration_id` string, required
      - `spaces` string[], required
      - `versions` integer, required: Versions in scope that miss a vector in a target space.
      - `segments` integer, required: Their segments, which the plugin embeds.
      - `input_tokens` integer, required: Estimated tokens the plugin embeds, one per four code points of segment text.
      - `estimated_seconds` number, double, required: How long the backfill should take, at the deployment's backfill.rate or the recent throughput, whichever is slower.
      - `duration_basis` 'rate' | 'recent_backfills' | 'recent_plugin_calls', required: What the duration comes from.
      - `estimated_cost_usd` number, double: Estimated cost in US dollars, rounded up to the cent, of the target spaces that declare an input_price in the plugin manifest; a space without one adds nothing. Absent when none declares one, so the cost is unknown.
      - `confirmation_required` boolean, required: The cost exceeds backfill.max_cost_without_confirmation, so starting the backfill needs confirm_cost.
  - `quarantine_reprocess` OperationQuarantineReprocess: What a quarantine reprocess covers, the plan it runs with and the dry run it followed.
    - `plugin` string
    - `code` string
    - `quarantined_after` string, date-time
    - `quarantined_before` string, date-time
    - `from_stage` 'normalization': The requested restart stage; omitted when retrying the failed step.
    - `plan_id` string, required: The Pipeline Plan it runs with, the one active when it was accepted.
    - `estimate` QuarantineReprocessEstimate, required
      - `versions` integer, required: Stuck Versions in scope.
      - `stages` object, required: Of them, how many failed at each step.
        - `normalization` integer, required
        - `ingestion` integer, required
      - `codes` object, required: Of them, how many by reason code.

## Other responses

- `default`: Structured admission error; 400 malformed, 401 unauthenticated, 403 without plugins:admin, 404 unknown target, 409 idempotency_conflict, 422 invalid_schema or invalid target, 503 storage unavailable. Discovery, plan compatibility and coverage failures are reported in the accepted Operation.

---

[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)