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 crash-consistent snapshot of an instance or volume
Creates a VM snapshot in the active scope from the VM snapshot creation form. The caller
chooses the snapshot source — a whole instance (every attached disk is captured) or a
single block volume — plus a snapshot name and an optional description. Snapshots are
crash-consistent and the source keeps running while the snapshot is captured; storage is
billed per captured GB·month pro-rata hourly. On acceptance the snapshot becomes
discoverable in the scoped list in its transitional CREATING state with the captured
size pre-allocated and usedGb still 0.
Validation: name is required and must be non-empty after trimming
(422 VALIDATION_ERROR); sourceKind is required and must be instance or volume, and
the matching source field must be present — sourceInstanceId for instance,
sourceVolume for volume — else 422; a referenced instance or volume that does not
exist or is not accessible in the scope maps to 404 NOT_FOUND; snapshot-storage quota
exhaustion maps to 409 QUOTA_EXCEEDED.
Async & state: Asynchronous (202). The snapshot resource is returned immediately in
CREATING state and transitions to terminal AVAILABLE on successful capture or
ERROR on failure (e.g. quiesce failed — disk busy); each transition is emitted as a
resource.updated SSE frame with a patch on status (and usedGb/incremental once
the capture completes) for the snapshot resource.
Errors: 401 unauthenticated; 403 caller lacks contributor/admin/owner on the scope;
404 unknown source instance/volume; 409 QUOTA_EXCEEDED when snapshot storage quota is
exhausted; 422 invalid body; 500 internal failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key
returns the originally created snapshot (same id, current state) without capturing a
duplicate.
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
Payload of the VM snapshot creation form.
name*stringSnapshot name; required, used to identify this snapshot.
^[^\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 <= 255sourceKind*stringSnapshot every disk of an instance, or a single block volume.
"instance""volume"sourceInstanceId?|Identifier of the source instance; required when sourceKind is instance, null otherwise.
sourceVolume?|Name of the source block volume; required when sourceKind is volume, null otherwise.
description?stringOptional free-text description (e.g. reason for the snapshot).
length <= 255Snapshot capture accepted; returned in its transitional CREATING state.
application/json- response
A crash-consistent snapshot of an instance (all disks) or a single block volume; billed per captured GB·month.
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.
name*stringsourceInstance*stringName of the source instance.
sourceInstanceId*stringInstance id behind sourceInstance, for deep-linking.
sourceVolume*stringName of the captured source volume.
sizeGb*integerAllocated (captured) size in GB.
usedGb*integerActually consumed storage in GB (lower than sizeGb for incremental snapshots; 0 while CREATING).
status*stringSnapshot lifecycle status.
"AVAILABLE""CREATING""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 Instance.statusReason.
description*stringFree-text description (e.g. reason for the snapshot); may be empty.
createdAt*stringCapture start timestamp (ISO 8601).
region*stringRegion identifier (e.g. ist-1).
encryption*stringEncryption mode of the snapshot data at rest.
"Platform-managed key""Customer-managed key""None"encrypted*booleanWhether the snapshot data is encrypted.
incremental*booleanWhether this capture stored only blocks changed since the previous snapshot.
osImage*stringOS image of the source at capture time (e.g. Ubuntu 24.04 LTS).
flavor*stringFlavor of the source instance at capture time.
curl -X POST "https://example.com/scopes/string/compute/snapshots" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "sourceKind": "instance" }'{ "origin": "portal", "id": "string", "name": "string", "sourceInstance": "string", "sourceInstanceId": "string", "sourceVolume": "string", "sizeGb": 0, "usedGb": 0, "status": "AVAILABLE", "statusReason": "string", "description": "string", "createdAt": "string", "region": "string", "encryption": "Platform-managed key", "encrypted": true, "incremental": true, "osImage": "string", "flavor": "string"}