List images install-wide (admin).
curl --request GET \ --url 'https://stratum.example.com/v1/images?scope=global&limit=200' \ --header 'Authorization: Bearer <token>'Install-scope admin endpoint. Lists every non-deleted image regardless of project ownership so bootstrap-admin / platform-admin can inventory + clean up global / region / failed-import images.
Optional scope filter narrows to global, region, or
project. Optional region filter narrows region-scoped
rows to a single region. Project-scoped images are visible
via this endpoint too — useful when a project image is
stuck in error and the project owner needs operator help.
Project users use GET /v1/projects/{pid}/compute/images
instead; that path enforces visibility OR (global + region
match + project owned).
Cursor-paginated. Ordered scope ASC, name ASC, created_at DESC, id DESC; when nextPageToken is present there are more
rows, and its absence means the last page. A token that cannot be parsed
is treated as no token, so a client gets the first page rather than a 400.
This endpoint previously returned every matching row with no limit at all,
which is the unbounded-response hazard listing.MaxRows exists to prevent.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Opaque cursor from a previous response’s nextPageToken. Omit for the
first page.
Responses
Section titled “Responses”Images.
A page of the install-wide image inventory.
Ordered scope ASC, name ASC, created_at DESC, id DESC. The trailing id is
load-bearing rather than decorative: live image names are unique per
(project_id, name), so two projects may each hold an image called ubuntu
and (scope, name) ties routinely. Without a unique tiebreaker the order is
not total, and a cursor sitting on a tie makes a client see a row twice or
miss one entirely.
object
object
P-system for global; owning project for scoped
arn:stratum:compute:<region>:<owner>:image/<id>,
the key a resource policy shares the image under
(PUT /v1/iam/resource-policies?resourceArn=).
The project that owns the image (always equal to
projectId): whose quota it counts against and whose editors may
share, publish and delete it.
Who may launch the image. private: the owner
project only. shared: plus every principal a resource policy on
the image ARN permits compute:UseImage (a project-kind principal
is what share writes). public: every project on the install.
Independent of scope, which is storage placement.
The requesting project’s relation to the image: self (owned),
system (the operator’s public catalog), shared (granted by a
resource policy), public (another project’s public image). Filled
on the project-scoped reads; absent on the admin surface.
The projects a resource policy on the image ARN grants
compute:UseImage — present on the OWNER’s reads only; a grantee
does not see who else was granted. Derived from the policy.
The source format the image was imported from (stored raw).
The storage classes (by name) a launch of this image may name as
rootStorageClass, or create-volume as storageClass:
active, on the image’s storage driver, and, for a driver whose clones
are pool-local (lvm-thin), on the pool the image is staged in. Any
other class is refused with 409 IMAGE_POOL_MISMATCH. The server
derives it from the rule it enforces, so a client offers this list
rather than recomputing it. Omitting the class always launches on the
image’s own storageClass. Absent when no class can be named or the
classes could not be read.
Where VMs launched from the image can run. A shared storage
class (Ceph) holds one copy every node reads: scope is all-nodes and
nodes is absent. A per-node class (lvm-thin) holds a copy per node, staged
from the image’s source: scope is nodes and nodes lists every node with
a staging row, so a VM runs only on the nodes in state ready. An image
uploaded through the API into a per-node class has its bytes only on the node
that received them (sourceUploadNode); every other node reports error
with the reason. Import it from a URL, or upload it into a shared class, to
run it everywhere. Absent while the image is not usable (not yet active)
or when the nodes could not be read.
object
Per-node staging state, ordered by node id; only when scope is nodes.
One node’s staging readiness for an image.
object
Per-node staging lifecycle. ready means a VM can clone its root volume from the local base LV here.
Failure detail when state is error; absent otherwise.
Size of the staged base LV in bytes; absent until known.
The bucket a bucket import read from.
The object key a bucket import read.
An uploaded image (POST /v1/images/upload): the node whose
control plane received the bytes. They stay staged there until the
import has written them into the storage class.
Every export job requested on the image.
One export job on an image.
object
Hex-encoded SHA256 of the uploaded object (succeeded only).
Why the job failed (failed only).
The instance a create-image was taken from.
The image that instance booted (lineage).
How a create-from-instance snapshot was taken:
the instance was stopped, the guest agent quiesced its
filesystems, or neither answered and the image is crash-consistent.
Absent on imported and promoted images.
The volumes the image carries; device 0 is the root snapshot, higher indexes are data volumes cloned at launch. Empty for single-volume images.
One volume an image carries. Device 0 is the root
(also sourceSnapshotId); higher indexes are data volumes cloned at
launch. A launch may override sizeBytes upward.
object
Where a create-from-instance is while the image
is pending: requested → stopping | freezing → snapshotting → thawing | starting → promoting → done, or failed (the image is
then error with stateReason). Absent on every other image.
Human-readable cause. Set when state is error, and
while deleting when the delete is BLOCKED: a volume
still CoW-cloned from this image, the backing store still held
open, or a transient backend error. A blocked delete is not a
failure — the image stays deleting and the worker re-attempts
it about once a minute until the blocker clears (a clone you
delete, a watcher that goes); nothing needs re-issuing. Cleared on
any other transition.
Read this before acting on an image that is not gone yet: it names the volume to delete, or tells you an operator is needed.
When the image became public: stamped by publish
and by the operator catalog’s activation, cleared by unpublish. A
private or shared image has none — this is a visibility stamp, not
“became available” (createdAt / state say that).
Set while the image is disabled.
The last launch from the image, stamped at most once an hour.
A scheduled deprecation not yet applied.
What references the image, on the owner’s reads:
the launch templates whose $Default or $Latest version names it.
A deregister without force is refused while this is non-empty.
object
AWS-shape resource tags. Freeform UTF-8 keys (1-128 bytes, no
leading/trailing whitespace) mapped to freeform UTF-8 values
(0-256 bytes). Max 50 tags per resource. Reserved prefixes
(stratum.dev/, stratum.platform_health., stratum:,
aws:) return 400 RESERVED_NAMESPACE on customer input.
PATCH replaces the whole map..
object
Opaque cursor for the next page. Present when more rows exist; absent on
the last page. Pass it back as page_token.
Distinct from the tenant image list, which carries isTruncated instead:
that endpoint returns a bounded prefix and can only tell you it is
incomplete, whereas this one can hand you the rest.
Example
{ "items": [ { "visibility": "private", "owner": "self", "format": "qcow2", "architecture": "amd64", "driver": "lvm-thin", "availability": { "scope": "all-nodes", "nodes": [ { "nodeId": "n-msst0001", "state": "pending" } ] }, "scope": "global", "exports": [ { "format": "qcow2", "state": "pending" } ], "consistency": "stopped", "createPhase": "requested", "state": "pending" } ]}Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}