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 point-in-time snapshot of a block volume
Creates a point-in-time snapshot of a block volume in the active scope from the
the snapshot creation form: the caller picks the source volume, a snapshot name, an optional
description, and whether the snapshot chains off the volume's previous snapshot (incremental,
app-side LINEAGE only — see the field docs) or starts a new chain. incremental 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, independently restorable and deletable. The snapshot
inherits the source volume's availability zone, encryption flag and KMS key, and records the
source's provisioned size as volumeSizeGb. On acceptance it appears in the scoped snapshot
list in status CREATING with progress advancing to 100.
Validation: sourceVolumeId must reference a live volume in the scope (unknown → 404
NOT_FOUND); the source volume must be in a snapshottable state (AVAILABLE or IN_USE — CREATING/
ERROR volumes → 409 CONFLICT); name must be non-empty and unique among the scope's snapshots
(duplicate → 409 CONFLICT); incremental: true records a chain off a prior snapshot of the same
volume — when none exists the snapshot is a chain root instead; the scope's snapshot
capacity/count quota is enforced (→ 409 QUOTA_EXCEEDED). RBAC: owner|admin|contributor.
Async & state: Asynchronous; returns 202 with the full VolumeSnapshot resource in its
transitional CREATING state (progress < 100). Terminal states: AVAILABLE on capture
completion, ERROR on failure. resource.updated SSE frames with kind "storage.snapshot" patch
status, progress and sizeGb as capture proceeds.
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scopeId or
sourceVolumeId; 409 CONFLICT duplicate name or source volume not snapshottable; 409
QUOTA_EXCEEDED snapshot quota; 422 missing/invalid fields; 429 rate limited; 500 unexpected
failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the
original 202 response (same snapshot id) instead of capturing a second snapshot.
This operation creates snapshots only; to create a volume from a snapshot, use storage.volume.create with sourceKind: snapshot.
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.
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
Request body for storage.snapshot.create — mirrors the snapshot creation form.
sourceVolumeId*stringIdentifier of the source block volume to snapshot.
name*stringSnapshot name — identifies this point-in-time copy; unique within the scope.
^[^\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?stringOptional free-text description (e.g. "Pre-migration checkpoint before schema change").
length <= 255incremental*booleanApp-side LINEAGE only: true to chain this snapshot off the volume's most recent snapshot (recording parentSnapshotId), false to start 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, independently restorable and deletable. A chain root is recorded when no prior snapshot exists.
Snapshot capture 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/snapshots" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "sourceVolumeId": "string", "name": "string", "incremental": true }'{ "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"}