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.
List and query VM snapshots in the active scope
Returns the VM snapshots visible in the active tenant/subscription/project scope,
as rendered by the Snapshots page table. This single collection endpoint serves BOTH the
plain route-load list and the search/filter/sort/pagination controls: free-text q
matches snapshot name and source (instance or volume) name; the UI's quick-filter chips
map to the status query parameter (Available / Creating); the table sorts on name,
sizeGb and createdAt via sort+order. No resource state is mutated by this call.
Validation: scopeId must resolve to a scope the caller can read or the request
fails with 403 FORBIDDEN; a non-enum status value, unknown sort fields or
out-of-range page/pageSize map to 422 VALIDATION_ERROR. Soft-deleted snapshots are
always excluded (deleted_at IS NULL).
Async & state: Synchronous read; no state change. In-flight captures surface as
CREATING rows and their completion (AVAILABLE) or failure (ERROR) arrives as
resource.updated SSE frames keyed by snapshot id with a patch on status/usedGb.
Errors: 401 when the session is missing or expired; 403 when the caller lacks reader
access to the scope; 422 on malformed query parameters; 500 on backend read-model failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required. Pagination is
stable per meta so repeated identical reads return consistent pages.
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.
region?stringRestrict the result set to a single region.
^[a-z][a-z0-9-]{1,39}$q?stringFree-text search.
sort?stringField to sort by (entity-specific; defaults to the entity's natural order).
order?stringSort direction.
"asc""asc""desc"page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050status?stringFilter by snapshot lifecycle status (UI quick-filter chips "Available" / "Creating").
"AVAILABLE""CREATING""ERROR"Paginated collection of VM snapshots visible in the scope.
application/json- response
data*array<>meta*Pagination envelope metadata. List responses are always { data, meta } — never a naked array.
curl -X GET "https://example.com/scopes/string/compute/snapshots"{ "data": [ { "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" } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}