Compute

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 machine image

DELETE
/scopes/{scopeId}/compute/images/{imageId}

Deletes a machine image the active scope's tenant OWNS, as triggered by the destructive "Delete" action in the Images page row menu and the image detail page header. The backing Glance image is removed from the cloud and the catalog row disappears from every scoped read, so the image stops consuming image quota and storage. Validation: imageId must reference an image visible in the scope (404 NOT_FOUND otherwise). Only a PRIVATE, tenant-owned image is deletable through this tenant route — a PUBLIC / platform / shared catalog image is refused with 403 FORBIDDEN, because it is managed by the platform operator (see the admin catalog surface). An image still PENDING (mid-capture) must finish or fail first (409 DEPENDENCY_BLOCKED); an image already DELETING is refused (409 CONFLICT); an image still in use by one or more live instances is refused with 409 DEPENDENCY_BLOCKED naming the blocking instances. The caller needs destructive-action rights on the scope (403 FORBIDDEN otherwise). Async & state: Asynchronous (202) returning an Operation handle. The image flips to the transitional DELETING status, the worker removes it from Glance (an already-absent provider image is tolerated) and then removes the catalog row; a resource.updated SSE frame patching status is emitted for the image id. On failed the image settles terminally on ERROR (never wedged in DELETING) and stays queryable so the delete can be retried. Errors: 401 unauthenticated; 403 insufficient role or a non-owned/public image; 404 unknown image; 409 DEPENDENCY_BLOCKED when the image is still capturing or in use, 409 CONFLICT when a delete is already in flight; 412 stale If-Match ETag; 500 internal failure. Idempotency/Concurrency: Idempotency-Key is optional (recommended) — replaying the same key returns the original Operation instead of enqueueing a second delete. If-Match with the image's current ETag guards against deleting a concurrently modified image (412 PRECONDITION_FAILED on mismatch).

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.

imageId*string

Identifier of the machine image to delete.

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; an Operation handle tracks the deletion workflow.

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/compute/images/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"}