Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Create a snapshot of a volume
Captures a crash-consistent, point-in-time snapshot of the block volume volumeId —
triggered by "Create snapshot" in the detail Snapshots tab, the per-row action, and as a
bulk action over selected rows in the Volumes page (one snapshot per selected volume). The source
volume stays online and writable during capture. Incremental snapshots store only blocks
changed since the previous snapshot of the volume; full snapshots store every allocated
block. The snapshot inherits the source's encryption posture (encrypted flag and KMS key)
and availability zone, records the source volume id/name and the provisioned size at capture
time, and is billed per stored GB·month.
Validation: volumeId must reference an existing volume in the scope (unknown → 404
NOT_FOUND); the volume state must permit snapshotting — CREATING/ERROR volumes are
rejected (→ 409 CONFLICT); name is required and non-empty (→ 422 VALIDATION_FAILED);
incremental: true falls back to a full capture when no prior snapshot chain exists; the
subscription's snapshot-storage quota must not be exhausted (→ 409 QUOTA_EXCEEDED — the UI
surfaces exactly this as a failed snapshot); caller needs owner|admin|contributor (→ 403).
Async & state: Asynchronous — returns 202 with the VolumeSnapshot resource in its
transitional CREATING state (progress 0–99). Terminal states: AVAILABLE
(progress 100) or ERROR. Progress is emitted as resource.updated SSE frames (kind
storage.snapshot, patch {status, progress, sizeGb}).
Errors: 401 unauthenticated; 403 caller lacks permission on the scope; 404 unknown
scopeId/volumeId; 409 CONFLICT volume state does not permit snapshot; 409 QUOTA_EXCEEDED
snapshot storage quota exhausted; 422 missing/empty name; 500 unexpected backend failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns
the originally created snapshot instead of capturing a duplicate point-in-time copy.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
volumeId*stringIdentifier of the source block volume.
Idempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
Payload for creating a point-in-time snapshot of a volume (the snapshot creation form).
name*stringSnapshot name used to identify this point-in-time copy; must be non-empty.
^[^\p{C}\p{Z}\x{10000}-\x{10FFFF}](?:[^\p{C}\p{Zl}\p{Zp}\x{10000}-\x{10FFFF}]*[^\p{C}\p{Z}\x{10000}-\x{10FFFF}])?$1 <= length <= 255description?|Optional description, e.g. the reason for the snapshot.
length <= 255incremental?booleanApp-side LINEAGE only: chain this snapshot off the volume's previous snapshot (recording parentSnapshotId) rather than starting a new chain. It does NOT make the snapshot a space-efficient delta — every volume snapshot is a full, independent Cinder COW snapshot at the full source-volume size. A chain root is recorded when no prior snapshot exists.
trueSnapshot creation accepted; returns the snapshot in its transitional CREATING state.
application/json- response
Block-volume snapshot read model rendered by the Snapshots page and the snapshot detail page.
origin?stringWhere the resource was made -- portal for a create on the console, api for an object made straight against the OpenStack API (CLI, Terraform, the Kubernetes cloud provider) that discovery adopted. Informational; nothing behaves differently. Absent from a backend that predates it, which means portal.
"portal""api""system""imported"id*stringSnapshot identifier (e.g. snap-pgdata-nightly).
name*stringSnapshot name (e.g. pgdata-nightly-0609).
status*stringLifecycle status of the snapshot.
"CREATING""AVAILABLE""ERROR"statusReason*|Human-readable, customer-facing reason the last lifecycle command on this resource failed (e.g. "The request could not be completed after repeated attempts. Try again, or contact support if it persists."); never raw provider text. Null while healthy, once a later settle clears it, or when the failure carried no detail. Mirrors Volume.statusReason.
sourceVolumeId*stringIdentifier of the source block volume.
sourceVolumeName*stringDisplay name of the source block volume at capture time.
sizeGb*integerStored snapshot size in GB. Every volume snapshot is a FULL, independent Cinder COW snapshot, so this is the full stored size (equal to the source volume size), NOT a delta — a snapshot flagged incremental is not space-efficient at the storage layer.
volumeSizeGb*integerLogical size of the source volume at capture time (full provisioned size, GB).
incremental*booleanApp-side LINEAGE marker only: true when this snapshot was created as a child in a snapshot chain (see parentSnapshotId), false for a chain root. It does NOT mean a space-efficient delta — Cinder volume snapshots do not chain natively, so EVERY snapshot (incremental or not) is a full, independent COW snapshot reporting the full source-volume size and is independently restorable/deletable with no dependency on other snapshots. (Real incremental chaining exists only for volume BACKUPS, not snapshots.)
encrypted*booleanWhether the snapshot blocks are encrypted (inherited from the source volume).
kmsKeyId*|KMS key encrypting the snapshot; null when platform-managed / encryption off.
availabilityZone*stringAvailability zone of the snapshot (inherited from the source volume, e.g. ist-1a).
childCount*integerNumber of snapshots that chain directly off this one in the app-side lineage graph (see incremental). Lineage bookkeeping only — deleting this snapshot never orphans data, since each child is itself a full, independent COW snapshot of the volume.
parentSnapshotId*|Id of the prior snapshot this one chains off in the app-side lineage graph; null for a chain root. Lineage metadata only — this snapshot is a full, independent COW snapshot regardless of any parent (see incremental).
progress*integerCapture progress percentage (0-100; 100 once AVAILABLE).
description*stringFree-text description (e.g. "Pre-migration checkpoint before schema change").
createdAt*stringCapture timestamp (ISO 8601).
date-timecurl -X POST "https://example.com/scopes/string/storage/volumes/string/snapshots" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "origin": "portal", "id": "string", "name": "string", "status": "CREATING", "statusReason": "string", "sourceVolumeId": "string", "sourceVolumeName": "string", "sizeGb": 0, "volumeSizeGb": 0, "incremental": true, "encrypted": true, "kmsKeyId": "string", "availabilityZone": "string", "childCount": 0, "parentSnapshotId": "string", "progress": 0, "description": "string", "createdAt": "2019-08-24T14:15:22Z"}