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
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).
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 <= 20050visibility?stringFilter buckets by visibility (mirrors the "Public" counter chip).
"Private""Public""Authenticated"versioned?booleanWhen true, return only buckets with object versioning enabled (mirrors the "Versioned" counter chip).
Paginated bucket collection for the active scope.
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/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 }}