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.
List and query machine images in the active scope
Returns the machine images (public marketplace images and private, org-authored golden
images) visible in the active tenant/subscription/project scope, as rendered by the
the Images page table. This single collection endpoint serves BOTH the plain route-load list and
the search/filter/sort/pagination controls: free-text q matches image name and OS, the
UI's quick-filter chips map to the visibility (Public/Private) and arch (arm64) query
parameters, and the table sorts on name, sizeGb and createdAt via sort+order.
No resource state is mutated by this call.
Validation: scopeId must resolve to an accessible scope or the request fails with
403 FORBIDDEN; unknown sort fields, non-enum visibility/arch/status/os values or
out-of-range page/pageSize map to 422 VALIDATION_ERROR. Soft-deleted images are always
excluded (deleted_at IS NULL).
Async & state: Synchronous read; no state change. Returns a stable snapshot suitable
for the table; live status transitions arrive over the realtime channel as
resource.updated frames keyed by image id.
Errors: 401 when the session is missing/expired; 403 when the caller lacks reader
access to the scope; 422 on malformed query parameters; 500 on backend read-model failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required. Pagination is
cursor-stable per meta so repeated reads with identical parameters return consistent pages.
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.
region?stringRestrict the result set to a single region.
^[a-z][a-z0-9-]{1,39}$q?stringFree-text search.
sort?stringField to sort by (entity-specific; defaults to the entity's natural order).
order?stringSort direction.
"asc""asc""desc"page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050visibility?stringFilter by image visibility (UI quick-filter chips "Public" / "Private").
"Public""Private"arch?stringFilter by CPU architecture (UI quick-filter chip "Arm64").
"x86_64""arm64"status?stringFilter by image lifecycle status.
"AVAILABLE""PENDING""DEPRECATED""DELETING""ERROR"os?stringFilter by operating-system family.
"ubuntu""debian""rhel""rocky""alma""windows""linux"Paginated collection of machine images visible in the scope.
application/json- response
data*array<>meta*Pagination envelope metadata. List responses are always { data, meta } — never a naked array.
curl -X GET "https://example.com/scopes/string/compute/images"{ "data": [ { "id": "string", "name": "string", "description": "string", "os": "ubuntu", "osName": "string", "osVersion": "string", "visibility": "Public", "sizeGb": 0, "arch": "x86_64", "source": { "kind": "instance", "ref": "string" }, "status": "AVAILABLE", "statusReason": "string", "encrypted": true, "kmsKeyId": "string", "minDiskGb": 0, "minRamMb": 0, "bootMode": "UEFI", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "shares": [ { "accountId": "string", "accountName": "string", "sharedAt": "2019-08-24T14:15:22Z" } ], "versions": [ { "version": "string", "createdAt": "2019-08-24T14:15:22Z", "sizeGb": 0, "isLatest": true, "note": "string" } ] } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}