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 block volumes in the active scope

GET
/scopes/{scopeId}/storage/volumes

Returns the paginated collection of block volumes in the active tenant → subscription → project scope, exactly as the Volumes page renders it: per-row identity (id, name, type), lifecycle status, size and provisioned IOPS, the attachment target (instance id/name and device path, or null when detached), encryption flag, availability zone and creation time. This single endpoint also serves the search/filter/sort/paginate behavior of the view (storage.volume.search_filter_sort): free-text q matches name, volume id or the attached instance name; the counter chips map to attachment=attached|detached and status=ERROR; sortable columns are name, size (sizeGb) and created (createdAt). No state is mutated. Validation: scopeId must reference a scope the caller can read (unknown → 404 via scope resolution, surfaced as 403/404); page/pageSize must be positive integers and sort one of name|size|created (invalid → 422 VALIDATION_FAILED); caller must hold reader-or-higher RBAC on the scope, otherwise 403 FORBIDDEN. Async & state: Synchronous read; no state change. Row-level changes (attach/detach, resize, status transitions CREATING→AVAILABLE/ERROR) arrive as resource.updated SSE frames (kind storage.volume, patch {status, sizeGb, attachedTo, updatedAt}). Errors: 401 missing/expired session; 403 caller lacks read access to the scope; 422 invalid pagination/sort/filter parameters; 500 unexpected backend failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

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 volume lifecycle status (the "Error" counter chip uses ERROR).

Value in"CREATING""AVAILABLE""IN_USE""AWAITING_TRANSFER""ERROR"
attachment?string

Filter by attachment state — the "Attached" / "Detached" counter chips.

Value in"attached""detached"
type?string

Filter by volume type.

Value in"Standard SSD""Premium SSD""Standard HDD"

Response Body

Paginated list of block volumes in the scope.

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/volumes"
{  "data": [    {      "origin": "portal",      "id": "string",      "name": "string",      "status": "CREATING",      "statusReason": "string",      "statusReasonCode": "string",      "sizeGb": 0,      "type": "Standard SSD",      "providerVolumeType": "string",      "attachedTo": {        "instanceId": "string",        "instanceName": "string",        "device": "string"      },      "bootable": true,      "encrypted": true,      "multiAttach": true,      "availabilityZone": "string",      "description": "string",      "source": {        "kind": "empty",        "ref": "string"      },      "kmsKeyId": "string",      "keyRotationDays": 0,      "pricePerGbMonthlyCents": 0,      "deletionProtection": true,      "tags": [        {          "key": "string",          "value": "string"        }      ],      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}