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 compute instance
Deletes the selected Instance (Delete action in the instance detail page and the instances table).
The backend enforces destructive-action permissions, checks attachments, dependants, locks, and
retention rules, then starts an asynchronous soft-delete workflow: the instance transitions to
status=DELETING (the UI polls it every 2.5s in that state) and is finally removed from the scoped
list, remaining recoverable per retention policy. Failure leaves the resource in a queryable
ERROR/previous state rather than half-deleted.
Validation: instance must exist and be visible → 404 NOT_FOUND; deletion must not be blocked
by an unresolved dependency (attached data disks pending detach, autoscale-group membership,
active capacity reservation) or a resource lock → 409 DEPENDENCY_BLOCKED; caller must hold a
destructive-capable role (owner/admin/contributor) → 403 FORBIDDEN.
Async & state: Asynchronous (202) returning an Operation record. State path: current →
DELETING → removed (terminal success) or ERROR (terminal failure, resource still queryable).
resource.updated SSE frames with kind=instance are emitted for the DELETING transition and the
final removal so the list view invalidates its cache.
Deletion protection: an instance whose deletionProtection is true is refused
with 409 DELETION_PROTECTED before it moves to DELETING; no Operation is opened and no
command is queued. Turn the protection off with the metadata PATCH, then retry. The same
409 refuses deleteRootVolume=true when the platform-provisioned root volume it would
delete has its own deletionProtection on; details.rootVolumeId / rootVolumeName
name that disk (keep it with deleteRootVolume=false, or turn its protection off).
Errors: 401 UNAUTHENTICATED; 403 FORBIDDEN; 404 NOT_FOUND for unknown/already-deleted
instance; 409 DEPENDENCY_BLOCKED when attachments/locks/retention prevent deletion; 409
DELETION_PROTECTED when the instance's deletion protection is on; 412
PRECONDITION_FAILED on stale If-Match; 500 INTERNAL.
Idempotency/Concurrency: Send Idempotency-Key; replaying returns the same Operation rather
than queuing a second delete. If-Match with the latest ETag guards against deleting a resource
that changed since last read (mismatch → 412). Deleting an instance already in DELETING returns
the in-flight Operation (no-op).
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.
instanceId*stringIdentifier of the compute instance.
deleteRootVolume?booleanWhether to also delete the instance's standalone Cinder root volume once the instance is removed. Defaults to true: omitting it deletes the root volume. Pass false to keep the volume — it then frees to AVAILABLE and CONTINUES TO BE BILLED, which is a deliberate choice to go on paying for a disk whose instance no longer exists. A root volume the caller BROUGHT (boot-from-volume) is never deleted here whatever this flag says; only a root volume the platform provisioned for this instance is reaped.
DATA DISKS ARE NEVER DELETED by an instance delete, whether they were attached at create time via dataDisks or later. They are independently named, independently managed volumes that the caller asked for explicitly and that routinely outlive the instance they were attached to; the delete only DETACHES them, so they become AVAILABLE and are deleted (or re-attached) from the Volumes surface. This flag does not and cannot apply to them. The root volume is the exception precisely because it is not independently requested: it comes into existence with the instance and has no meaning without it.
trueIdempotency-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; returns the tracking Operation while the instance is in DELETING state.
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/instances/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"}