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 object storage buckets

GET
/scopes/{scopeId}/storage/buckets

Returns the paginated collection of object storage buckets in the active tenant → subscription → project scope, as the console's bucket list shows it: name with default storage class and encryption mode, visibility (Private or Public; a legacy bucket may still report Authenticated, which is effectively private), object count, total size in bytes, region and creation time. This single endpoint serves both the plain route-load listing and the interactive search/filter/sort/pagination controls: q performs a case-insensitive substring match on the bucket name, the visibility filter and versioned flag mirror the "Public" and "Versioned" counter chips. sort and order are not applied: buckets are always returned oldest first (by creation time). No resource state is mutated. Validation: scopeId must reference a scope the caller can read (unknown → 404 NOT_FOUND); visibility must be one of Private|Public|Authenticated, page must be a positive integer and pageSize 1–200 (invalid → 422 VALIDATION_FAILED); caller must hold reader-or-higher RBAC on the scope, otherwise 403 FORBIDDEN. Async & state: Synchronous read; no state change. Subsequent bucket changes (object count and size drift, visibility flips, deletion) arrive as resource.updated SSE frames (kind storage.bucket, patch {objectCount, sizeBytes, visibility, versioning}). Errors: 401 missing/expired session; 403 caller lacks read access to the scope; 404 unknown scopeId; 422 malformed query parameters; 500 unexpected backend failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. Soft-deleted buckets are always excluded (WHERE deleted_at IS NULL).

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
visibility?string

Filter buckets by visibility (mirrors the "Public" counter chip).

Value in"Private""Public""Authenticated"
versioned?boolean

When true, return only buckets with object versioning enabled (mirrors the "Versioned" counter chip).

Response Body

Paginated bucket collection for the active 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/buckets"
{  "data": [    {      "origin": "portal",      "status": "creating",      "id": "string",      "name": "string",      "region": "string",      "objectCount": 0,      "sizeBytes": 0,      "visibility": "Private",      "versioning": true,      "encryption": "NONE",      "kmsKeyId": "string",      "storageClass": "Standard",      "blockPublicAcls": true,      "blockPublicPolicy": true,      "objectLock": true,      "accessLogging": true,      "logTarget": "string",      "owner": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}