Compute

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

POST
/scopes/{scopeId}/compute/snapshots

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Header Parameters

Idempotency-Key*string

Required: 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.

Formatuuid

Request Body

application/json
  1. body

Payload of the VM snapshot creation form.

name*string

Snapshot name; required, used to identify this snapshot.

Match^[^\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}])?$
Length1 <= length <= 255
sourceKind*string

Snapshot every disk of an instance, or a single block volume.

Value in"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?string

Optional free-text description (e.g. reason for the snapshot).

Lengthlength <= 255

Response Body

Snapshot capture accepted; returned in its transitional CREATING state.

application/json
  1. response

A crash-consistent snapshot of an instance (all disks) or a single block volume; billed per captured GB·month.

origin?string

Where 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.

Value in"portal""api""system""imported"
id*string

Snapshot identifier.

name*string
sourceInstance*string

Name of the source instance.

sourceInstanceId*string

Instance id behind sourceInstance, for deep-linking.

sourceVolume*string

Name of the captured source volume.

sizeGb*integer

Allocated (captured) size in GB.

usedGb*integer

Actually consumed storage in GB (lower than sizeGb for incremental snapshots; 0 while CREATING).

status*string

Snapshot lifecycle status.

Value in"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*string

Free-text description (e.g. reason for the snapshot); may be empty.

createdAt*string

Capture start timestamp (ISO 8601).

region*string

Region identifier (e.g. ist-1).

encryption*string

Encryption mode of the snapshot data at rest.

Value in"Platform-managed key""Customer-managed key""None"
encrypted*boolean

Whether the snapshot data is encrypted.

incremental*boolean

Whether this capture stored only blocks changed since the previous snapshot.

osImage*string

OS image of the source at capture time (e.g. Ubuntu 24.04 LTS).

flavor*string

Flavor 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"}