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.

Delete a bucket

DELETE
/scopes/{scopeId}/storage/buckets/{bucketId}

Deletes the bucket bucketId from the active scope. The UI exposes this from the bucket detail header ("Delete"), the list row menu ("Delete bucket") and as a bulk action over selected rows. Deletion enters a visible asynchronous workflow (soft delete): the bucket stops accepting new writes, its objects and versions are drained, and the resource then disappears from scoped listings. A failed deletion leaves the bucket in a recoverable, queryable state. Validation: bucketId must reference an existing, non-deleted bucket in the scope (unknown → 404 NOT_FOUND); deletion must not be blocked by an unresolved dependency such as remaining objects when force-emptying is not permitted, or access-log delivery from another bucket (blocked → 409 DEPENDENCY_BLOCKED); a legacy delete-protected bucket (objectLock: true) that still holds objects cannot be deleted through this API (→ 409 LOCKED); a bucket already deleting cannot be deleted again (→ 409 CONFLICT, no second Operation); caller must hold a destructive-action role (owner|admin|contributor), otherwise 403 FORBIDDEN. Async & state: Asynchronous — returns 202 with an Operation. The bucket transitions active → deleting → deleted (soft delete; subsequent reads return 404 while activity retains the audit trail). Progress is emitted as resource.updated SSE frames (kind storage.bucket, patch {status, objectCount, sizeBytes}) followed by a terminal operation.completed frame. Errors: 401 unauthenticated; 403 caller lacks destructive permission; 404 unknown scopeId/bucketId; 409 DEPENDENCY_BLOCKED objects or log-delivery dependants block removal; 409 LOCKED legacy delete protection, the bucket still holds objects; 409 CONFLICT the bucket is already being deleted; 412 If-Match ETag does not match the current bucket revision; 500 unexpected backend failure. Idempotency/Concurrency: Idempotency-Key is optional; replaying the same key returns the original 202 Operation without enqueuing a second deletion. If-Match with the ETag from the detail read protects against deleting a concurrently modified bucket.

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.

bucketId*string

Identifier of the bucket.

Header Parameters

Idempotency-Key?string

Optional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.

Formatuuid
If-Match?string

ETag for optimistic concurrency on mutations/deletes; mismatch results in 412.

Response Body

Deletion accepted; returns the tracking Operation.

application/json
  1. response

A long-running operation record. GET /operations/{operationId} returns its current state.

id*string

Operation identifier, unique platform-wide.

action*string

Canonical action id that started this operation, e.g. compute.instance.create.

state*OperationState

State machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.

Value in"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"
resourceKind?|

Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.

resourceId?|

Identifier of the target resource; null until the resource is allocated.

resourceName?|

Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).

principalId?|

Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.

sourceIp?|

Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).

progressPercent?|

Best-effort progress; null when the action does not report progress.

Range0 <= value <= 100
error?|null

Populated only when state is FAILED (or CANCELLED with partial rollback notes).

warning?|null

Non-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.

startedAt?|

When the worker began executing; null while PENDING.

finishedAt?|

When a terminal state was reached; null while transitional.

createdAt*string
updatedAt*string
curl -X DELETE "https://example.com/scopes/string/storage/buckets/string"
{  "id": "string",  "action": "string",  "state": "PENDING",  "resourceKind": "string",  "resourceId": "string",  "resourceName": "string",  "principalId": "string",  "sourceIp": "string",  "progressPercent": 0,  "error": {    "code": "string",    "message": "string",    "field": "string",    "details": {},    "retryable": false  },  "warning": {    "code": "string",    "message": "string",    "field": "string",    "details": {},    "retryable": false  },  "startedAt": "string",  "finishedAt": "string",  "createdAt": "string",  "updatedAt": "string"}