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
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.
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 <= 20050protocol?stringFilter by share protocol (the "NFS"/"SMB" counter pills in the File shares page).
"NFS""SMB"Paginated page of file shares 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/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 }}