Backup policy API

Backup policy API

Define selection, calendar execution, consistency, destination, and retention.

Backup policies schedule independent recovery copies. Each run resolves the policy revision and selected source IDs before starting capture.

POST/organizations/{organization_id}/projects/{project_id}/backup-policies
Scope
backups:write
Auth
Bearer API key

Creates a scheduled backup policy.

Send a name, selection, schedule, destination, and retention definition. Selection contains either volume_ids, consistency_group_ids, or a label selector; combining selector forms is rejected.

To capture an application consistency group every day at 02:00 UTC, send:

JSON
{
  "name": "ledger-daily",
  "selection": { "consistency_group_ids": ["cg_ledger"] },
  "schedule": { "expression": "0 2 * * *", "time_zone": "UTC" },
  "destination_id": "bkd_archive",
  "consistency": "application",
  "hook_set_id": "hooks_ledger",
  "retention": { "daily": 14, "weekly": 8 },
  "overlap": "skip",
  "enabled": true
}

enabled defaults to true; consistency defaults to crash; overlap defaults to skip and also accepts queue. Retention tier counts are non-negative integers and at least one tier must retain a point. Invalid calendar expressions or time zones return 422 invalid_schedule.

Returns 201 with policy ID and revision. The definition is validated, but creation does not create an immediate backup unless a separate run is requested.

Update

PATCH/organizations/{organization_id}/projects/{project_id}/backup-policies/{policy_id}
Scope
backups:write
Auth
Bearer API key

Updates the backup policy for subsequent execution and retention evaluation.

Requires backups:write and If-Match. Supplied selection, schedule, and retention objects replace their whole stored value. Omission preserves a field. Explicit null is invalid for required objects.

A running backup keeps its pinned policy revision. Disabling the policy prevents new scheduled runs and does not cancel a run already copying data. Reducing retention can make older completed points eligible on the next cleanup evaluation.

Preview selection and expiration

POST/organizations/{organization_id}/projects/{project_id}/backup-policies/{policy_id}/preview
Scope
backups:write
Auth
Bearer API key

Returns current selected sources, unsupported consistency members, and recovery points eligible under the proposed retention. It creates no capture and reserves no capacity.

The preview includes retained sources that no longer exist. A source deletion does not make its remaining backups disappear from retention accounting.

Run and delete

POST/organizations/{organization_id}/projects/{project_id}/backup-policies/{policy_id}/runs
Scope
backups:write
Auth
Bearer API key

Starts a manual backup run using the policy.

Returns 202 with a new run and operation. It supports idempotency keys. A manual run obeys destination and consistency policy just like a scheduled run.

DELETE/organizations/{organization_id}/projects/{project_id}/backup-policies/{policy_id}
Scope
backups:write
Auth
Bearer API key

Deletes the policy and stops future scheduling while preserving retained recovery points.

Deleting the policy requires its ETag and stops future scheduling. Retained recovery points remain governed by their recorded retention and holds. Removing the policy is not a request to purge the backup destination.

Use Backup Run API to inspect execution, application hooks for prepare/resume behavior, and retention for shared data and legal holds.