Storage

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

GET
/scopes/{scopeId}/storage/snapshots

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.

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.

Query Parameters

region?string

Restrict the result set to a single region.

Match^[a-z][a-z0-9-]{1,39}$
q?string

Free-text search.

sort?string

Field to sort by (entity-specific; defaults to the entity's natural order).

order?string

Sort direction.

Default"asc"
Value in"asc""desc"
page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50
status?string

Filter by snapshot lifecycle status (the "Available"/"In progress"/"Error" counter pills).

Value in"CREATING""AVAILABLE""ERROR"

Response Body

Paginated page of volume snapshots matching the supplied search/filter/sort criteria.

application/json
  1. 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  }}