> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete an unused image
> Deleting a platform image requires a principal acting in the platform
account with `compute:DeleteImage`; other accounts receive 403.
Refuses with 409 and code IMAGE_IN_USE if any instance (in any state)
or instance-pool template references this image. The image is unchanged.
The existing code/message error envelope has no structured details field;
message names both counts, including zero, for example:
"image is in use by 2 instances and 0 pools".
An unused image transitions to status=deleting and its snapshot and base
data are reclaimed asynchronously. GET returns the deleting resource until
cleanup completes, then 404. A repeated DELETE returns 404, including
during cleanup. Withdrawn images follow the same reference checks.
Primary IAM action: **`compute:DeleteImage`**.
Deleting a platform image requires a principal acting in the platform
account with `compute:DeleteImage`; other accounts receive 403.
See [COMPUTE permissions](/compute/permissions) for policy examples.
## OpenAPI
````yaml /api-reference/specs/compute.yaml delete /v1/images/{image_id}
openapi: 3.0.3
info:
title: Basaltic Compute API
version: 1.0.0
description: |
Virtual machine instances, and the images, flavors, SSH keypairs and
instance pools they are built from. Covers the whole instance lifecycle:
start, stop, reboot, resize and reinstall.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://compute.{region}.basaltic.sh
description: Regional API endpoint
variables:
region:
default: sa-saopaulo-1
description: Region code
security:
- BearerAuth: []
paths:
/v1/images/{image_id}:
delete:
tags:
- Images
summary: Delete an unused image
description: >
Deleting a platform image requires a principal acting in the platform
account with `compute:DeleteImage`; other accounts receive 403.
Refuses with 409 and code IMAGE_IN_USE if any instance (in any state)
or instance-pool template references this image. The image is unchanged.
The existing code/message error envelope has no structured details
field;
message names both counts, including zero, for example:
"image is in use by 2 instances and 0 pools".
An unused image transitions to status=deleting and its snapshot and base
data are reclaimed asynchronously. GET returns the deleting resource
until
cleanup completes, then 404. A repeated DELETE returns 404, including
during cleanup. Withdrawn images follow the same reference checks.
operationId: deleteImage
parameters:
- $ref: '#/components/parameters/ImageId'
responses:
'202':
description: Image accepted for asynchronous deletion (status=deleting)
content:
application/json:
schema:
$ref: '#/components/schemas/ImageResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
security:
- BearerAuth: []
components:
parameters:
ImageId:
name: image_id
in: path
description: Image ID
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
schemas:
ImageResponse:
type: object
properties:
image:
$ref: '#/components/schemas/Image'
required:
- image
Image:
type: object
properties:
id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
crn:
type: string
example: >-
crn:compute:sa-saopaulo-1:my-account:image/ubuntu-24.04/architecture/amd64/version/20260901
name:
description: >-
Resource names must not start with the literal crn: prefix or be
UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
case).
type: string
example: ubuntu-24.04
description:
type: string
example: Ubuntu 24.04 LTS (Noble Numbat)
os:
type: string
example: ubuntu
os_version:
type: string
example: '24.04'
architecture:
type: string
example: amd64
version:
type: string
description: |
The build's identity within its name. Unique there: a name is a
movable tag, so it can't also be what tells two builds apart.
Stamped as a UTC timestamp when the uploader didn't choose one.
example: '20260807'
is_current:
type: boolean
description: |
Whether this is the version resolve-by-name returns for its
(name, architecture) — i.e. the name's current tag target.
example: true
eol_date:
type: string
format: date
description: |
The day this image's OS release stops receiving free security
updates for a default install. Absent when nobody has recorded
one — which means unknown, not "supported indefinitely".
Platform images are withdrawn from the catalog a grace period
after this date. They stay bootable by id until then, and the
date is published well ahead of it so you can plan the move.
example: '2026-08-31'
size_bytes:
type: integer
format: int64
example: 2361393152
min_disk_gb:
type: integer
minimum: 0
maximum: 16384
example: 10
min_ram_mb:
type: integer
minimum: 0
example: 1024
status:
type: string
enum:
- pending
- importing
- active
- error
- deleting
- withdrawn
description: >-
Error exactly while an active error fault exists; import and
deletion progress remain independently retryable.
example: active
withdrawal_reason:
type: string
description: >
Why this image was withdrawn. Present for withdrawn images,
including those with an independent error fault:
end_of_life for platform release withdrawal (see eol_date), or
legacy for a migrated withdrawal whose original reason is unknown.
Withdrawn images retain their data but cannot be launched.
example: end_of_life
faults:
type: array
readOnly: true
description: >-
Active faults, newest first. Empty for a healthy image. Error faults
set status to error without disabling an eligible import or cleanup
retry.
items:
$ref: '#/components/schemas/Fault'
tags:
$ref: '#/components/schemas/Tags'
attributes:
type: object
additionalProperties:
type: string
created_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
updated_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
required:
- id
- crn
- name
- version
- architecture
- status
- faults
- created_at
- updated_at
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Error code identifying the type of error
example: INVALID_INPUT
message:
type: string
description: Human-readable error message
example: Invalid request parameters
request_id:
type: string
format: uuid
description: Request ID for debugging
example: 550e8400-e29b-41d4-a716-446655440000
Fault:
type: object
required:
- code
- severity
- message
- details
- first_at
- last_at
- occurrences
properties:
code:
type: string
description: Stable machine-readable code owned by the reporting operation.
example: BACKUP_FAILED
severity:
type: string
enum:
- error
- warning
message:
type: string
example: Backup upload failed.
details:
type: object
nullable: true
additionalProperties: true
description: Structured context; legacy strings are preserved in legacy_text.
first_at:
type: string
format: date-time
description: First observation in this active occurrence series.
last_at:
type: string
format: date-time
description: Latest observation in this active occurrence series.
occurrences:
type: integer
minimum: 1
example: 1
Tags:
type: object
additionalProperties:
type: string
example:
environment: production
team: backend
responses:
Unauthorized:
description: Authentication required or token invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Resource not found
request_id: 550e8400-e29b-41d4-a716-446655440000
Conflict:
description: Resource conflict (e.g., already exists, invalid state)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: CONFLICT
message: Resource with this name already exists
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
An OAuth 2.0 bearer token, sent as `Authorization: Bearer `.
This is the recommended way to authenticate.
Get one by exchanging a service account's access key pair at
`POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
standard client-credentials grant, so any OAuth-aware library will
obtain and refresh it for you.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Tokens last an hour by default. The same access key pair is separately
your AWS SigV4 credential for the S3-compatible object endpoint, which
speaks nothing else.
````