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.
Restore a block-volume snapshot into a new volume
Restores the snapshot into a brand-new volume (the snapshot and its source volume are left
untouched). The new volume is sized from the snapshot's source and is created with the
requested name, tier and availability zone; when availabilityZone is omitted or null the
snapshot's own zone is used. A restore of an ENCRYPTED snapshot is encrypted too, on the
encrypted variant of the requested tier.
Validation: volumeName is required; volumeType must be a VolumeType value (default
Standard SSD) → else 422 VALIDATION_FAILED (field volumeType); unknown body properties →
422; a missing Idempotency-Key from an API token or service-account caller → 400
IDEMPOTENCY_KEY_REQUIRED; unknown / soft-deleted / out-of-scope snapshot → 404
NOT_FOUND; the region must offer the volumes module and the requested tier (and, for an
encrypted snapshot, its encrypted variant) → else 404 NOT_FOUND; the snapshot must be
AVAILABLE → else 409 CONFLICT (details.status); a paused (frozen) subscription accepts no
new provisioning → 409 CONFLICT; the new volume must fit the subscription's volume count and
gigabyte quota → else 409 QUOTA_EXCEEDED. All checks run before any operation exists.
RBAC: MANAGE on storage plus the storage:write token scope. A tenant on non-payment
hold is read-only → 403.
Async & state: Asynchronous — returns 202 with the tracking Operation
(storage.snapshot.restore); the worker materialises the new Volume from the volume the
provider creates off the snapshot.
Errors: 401 unauthenticated; 403 caller lacks storage MANAGE / token scope, or tenant on
hold; 404 unknown snapshot, or module / tier not offered in the region; 409 snapshot not
AVAILABLE, subscription paused, quota exceeded, or the same Idempotency-Key in flight / used
with a different body; 400 IDEMPOTENCY_KEY_REQUIRED (API token or service-account caller
without the key); 422 invalid body; 500 internal failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key and body
returns the original 202 Operation instead of creating a second volume.
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.
snapshotId*stringIdentifier of the snapshot to restore.
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
Body of POST /scopes/{scopeId}/storage/snapshots/{snapshotId}/actions/restore — the new volume to restore into.
volumeName*stringName of the new volume.
volumeType?stringTier of the new volume.
"Standard SSD""Standard SSD""Premium SSD""Standard HDD"availabilityZone?|Availability zone of the new volume; omitted or null uses the snapshot's own zone.
Restore accepted; the tracking Operation is returned.
application/json- response
A long-running operation record. GET /operations/{operationId} returns its current state.
id*stringOperation identifier, unique platform-wide.
action*stringCanonical action id that started this operation, e.g. compute.instance.create.
state*OperationStateState machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.
"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"resourceKind?|Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.
resourceId?|Identifier of the target resource; null until the resource is allocated.
resourceName?|Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).
principalId?|Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.
sourceIp?|Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).
progressPercent?|Best-effort progress; null when the action does not report progress.
0 <= value <= 100error?|nullPopulated only when state is FAILED (or CANCELLED with partial rollback notes).
warning?|nullNon-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.
startedAt?|When the worker began executing; null while PENDING.
finishedAt?|When a terminal state was reached; null while transitional.
createdAt*stringupdatedAt*stringcurl -X POST "https://example.com/scopes/string/storage/snapshots/string/actions/restore" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "volumeName": "string" }'{ "id": "string", "action": "string", "state": "PENDING", "resourceKind": "string", "resourceId": "string", "resourceName": "string", "principalId": "string", "sourceIp": "string", "progressPercent": 0, "error": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "warning": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "startedAt": "string", "finishedAt": "string", "createdAt": "string", "updatedAt": "string"}