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 block-volume snapshots in the active scope
Returns the block-volume snapshot inventory for the active tenant/subscription/project
scope, loaded on the Snapshots page route. This single operation covers BOTH the plain
route-load list (storage.snapshot.list) and the search/filter/sort/paginate behavior
(storage.snapshot.search_filter_sort): both UI actions hit the same GET on this collection.
Free-text q matches the snapshot name, source volume name, or snapshot id; the status
filter (the All / Available / In progress / Error counter pills) AND-combines with it.
Sortable columns include name and sizeGb. Each row carries the read model the table renders:
name, status, source volume id+name, stored size vs. source volume size, incremental flag,
encryption + KMS key, availability zone, child (derived) count, capture progress and createdAt.
Validation: scopeId must resolve to a scope the caller can access (unknown or
soft-deleted → 404 NOT_FOUND); status must be one of CREATING|AVAILABLE|ERROR; page ≥ 1 and
pageSize within server bounds — any malformed filter/sort/pagination value → 422
VALIDATION_ERROR. RBAC: any scope role (owner|admin|contributor|reader|billing) may read.
Async & state: Synchronous read; no state change. Capture progress (CREATING → AVAILABLE,
progress 0→100) and failures (→ ERROR) arrive as resource.updated SSE frames with kind
"storage.snapshot", not via this call.
Errors: 401 missing/expired session; 403 authenticated but no role on the scope; 404
unknown scopeId; 422 malformed query parameter; 500 unexpected backend failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required. Repeated identical
requests against the same read-model snapshot return identical 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 (the "Available"/"In progress"/"Error" counter pills).
"CREATING""AVAILABLE""ERROR"Paginated page of volume snapshots matching the supplied search/filter/sort criteria.
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/storage/snapshots"{ "data": [ { "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" } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}