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 VM snapshot
Soft-deletes the selected VM snapshot, as triggered by the destructive "Delete" action
in the Snapshots page row menu and the VM snapshot detail page header. The snapshot is
removed from all scoped lists, its billed storage stops accruing, and the freed capacity
is reclaimed asynchronously. Failure leaves the snapshot in a recoverable, queryable
state.
Validation: the snapshot must exist in the scope and not already be soft-deleted
(404 NOT_FOUND); deletion must not be blocked by an unresolved dependency — a snapshot
that is the source of a machine image, of an in-flight "create instance from snapshot"
launch, or that a retention rule pins, maps to 409 DEPENDENCY_BLOCKED with the blocker
identified; a snapshot still CREATING must finish or fail before it can be deleted
(409 DEPENDENCY_BLOCKED). The caller needs destructive-action rights on the scope
(403 FORBIDDEN otherwise).
Async & state: Asynchronous (202) returning an Operation handle. The snapshot enters
a visible deletion workflow and is then soft-deleted (excluded from reads via
deleted_at); a resource.deleted-style resource.updated SSE frame is emitted for
the snapshot id when the Operation reaches succeeded; on failed the snapshot remains
queryable in its prior state.
Errors: 401 unauthenticated; 403 insufficient role for a destructive action;
404 unknown snapshot; 409 DEPENDENCY_BLOCKED when an image, launch or retention rule
depends on the snapshot; 412 stale If-Match ETag; 500 internal failure.
Idempotency/Concurrency: Idempotency-Key recommended; replaying the same key
returns the original Operation instead of enqueueing a second delete. If-Match with
the snapshot's current ETag guards against deleting a concurrently modified resource
(412 PRECONDITION_FAILED on mismatch).
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.
snapshotId*stringIdentifier of the VM snapshot to delete.
Idempotency-Key?stringOptional; 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.
uuidIf-Match?stringETag for optimistic concurrency on mutations/deletes; mismatch results in 412.
Deletion accepted; an Operation handle tracks the deletion workflow.
application/json- response
A long-running operation record. GET /operations/{operationId} returns its current state.
id*stringOperation identifier, unique platform-wide.
action*stringCanonical action id that started this operation, e.g. compute.instance.create.
state*OperationStateState machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.
"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.
0 <= value <= 100error?|nullPopulated only when state is FAILED (or CANCELLED with partial rollback notes).
warning?|nullNon-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*stringupdatedAt*stringcurl -X DELETE "https://example.com/scopes/string/compute/snapshots/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"}