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 NFS/SMB file shares in the active scope

GET
/scopes/{scopeId}/storage/file-shares

Returns the managed file-share inventory (NFS for Linux/Unix clients, SMB for Windows/Active Directory clients) for the active tenant/subscription/project scope, loaded on the the File shares page route. This single operation covers BOTH the plain route-load list (storage.file_share.list) and the search/filter/sort/paginate behavior (storage.file_share.search_filter_sort): both UI actions hit the same GET on this collection. Free-text q matches the share name; the protocol filter (the All / NFS / SMB counter pills) AND-combines with it. Sortable columns are name, provisionedGb and createdAt. Each row carries the full read model the table renders: name, description, protocol + protocolVersion, status, tier, provisioned/used capacity, IOPS, throughput, encryption, mount path/targets, snapshots, access rules, AD domain and the per-GB monthly price in hundredths of the currency unit. Validation: scopeId must resolve to a scope the caller can access (unknown or soft-deleted → 404 NOT_FOUND); protocol must be one of NFS|SMB; sort one of name|provisionedGb|createdAt; 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. Share lifecycle transitions (CREATING→AVAILABLE, UPDATING→AVAILABLE, →ERROR) arrive as resource.updated SSE frames with kind "storage.file_share", 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
protocol?string

Filter by share protocol (the "NFS"/"SMB" counter pills in the File shares page).

Value in"NFS""SMB"

Response Body

Paginated page of file shares 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/file-shares"
{  "data": [    {      "origin": "portal",      "id": "string",      "name": "string",      "description": "string",      "protocol": "NFS",      "protocolVersion": "string",      "status": "AVAILABLE",      "statusReason": "string",      "tier": "Standard",      "provisionedGb": 0,      "usedGb": 0,      "iops": 0,      "throughputMbps": 0,      "encrypted": true,      "kmsKeyId": "string",      "mountPath": "string",      "mountTargets": [        {          "id": "string",          "network": "string",          "subnet": "string",          "ip": "string",          "zone": "string"        }      ],      "snapshots": [        {          "id": "string",          "name": "string",          "sizeGb": 0,          "createdAt": "2019-08-24T14:15:22Z",          "automatic": true        }      ],      "accessRules": [        {          "id": "string",          "source": "string",          "permission": "rw",          "rootSquash": true,          "description": "string"        }      ],      "adDomain": "string",      "pricePerGbMonthlyCents": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}