# images (/docs/reference/api/images) > The images group is the catalog of OS images and ramdisks that deploys write to disk. An image is registered by its digest and source URL, never uploaded, and a signature from a signer on the tenant's or the platform's allowlist marks it verified. Unsigned images stay private to their tenant; only verified images can be made public. See [Profiles and images](/docs/guides/bare-metal/profiles-and-images). The images group is the catalog of OS images and ramdisks that deploys write to disk. An image is registered by its digest and source URL, never uploaded, and a signature from a signer on the tenant's or the platform's allowlist marks it verified. Unsigned images stay private to their tenant; only verified images can be made public. See [Profiles and images](/docs/guides/bare-metal/profiles-and-images). All 4 methods are served by this release. | Method | Kind | Authorization | Phase | Status | | ----------------------- | -------- | ----------------------------------------------------------------------------------------- | ----- | ---------- | | [`register`](#register) | mutation | `compute:images:publish` @ `compute-tenant` or `compute:images:publish` @ `compute-fleet` | v0.2 | registered | | [`get`](#get) | read | `compute:images:read` @ `compute-image` | v0.2 | registered | | [`list`](#list) | read | `compute:images:read` @ `compute-tenant` + items | v0.2 | registered | | [`promote`](#promote) | mutation | `compute:images:publish` @ `compute-image` | v0.2 | registered | ## register [#register] `POST /api/compute/images/register` Records an image by `ref` (`name@version`), format, digest and `https://` or `oci://` source in the tenant's catalog; with a valid signature it is marked verified. * Decided as `compute:images:publish` on the tenant. * `signature` and `signerId` go together. The signature must verify against that signer on the tenant's allowlist or the platform's, else `INVALID_INPUT`. * A `ramdisk` must be signed by a platform signer (`INVALID_INPUT` otherwise). * `CONFLICT` when the tenant already has that `ref`, so a repeated call does not create a second image. The new image is private. Site agents whose pools pre-warm this ref (`policy.prewarmImages`) get their desired state refreshed. * **Kind:** mutation * **Authorization:** `compute:images:publish` @ `compute-tenant` or `compute:images:publish` @ `compute-fleet` * **Module:** `provision` * **Phase:** v0.2 (registered) **Input** | Field | Type | Required | Constraints | | ------------- | ----------------------------- | -------- | ---------------------------------------------------------- | | `tenantId` | string | yes | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$` | | `ref` | string | yes | 1-200 characters | | `kind` | one of `os`, `ramdisk` | | default `"os"` | | `format` | one of `raw`, `qcow2`, `iso` | yes | | | `compression` | one of `none`, `zstd`, `gzip` | | default `"none"` | | `sha256` | string | yes | 1-64 characters; matches `^[0-9A-Fa-f]{64}$` | | `sizeBytes` | integer | | at least 0 | | `source` | string | yes | 1-2048 characters | | `signature` | string | | 1-1024 characters | | `signerId` | string | | 1-128 characters | ## get [#get] `POST /api/compute/images/get` Returns one image the tenant owns, or a public one, by its `img_` id. `NOT_FOUND` when the image does not exist, is deleted, or belongs to another tenant and is not public. * **Kind:** read * **Authorization:** `compute:images:read` @ `compute-image` * **Module:** `provision` * **Phase:** v0.2 (registered) **Input** | Field | Type | Required | Constraints | | ---------- | ------ | -------- | ---------------------------------------------------------------- | | `tenantId` | string | yes | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$` | | `imageId` | string | yes | at most 56 characters; matches `^img_[0-9a-hjkmnp-tv-z]{26,52}$` | ## list [#list] `POST /api/compute/images/list` Returns a page of the tenant's own images and public ones, ordered by `ref`, optionally filtered by `kind` (`os` or `ramdisk`). `limit` defaults to 50 and is at most 200; pass the returned `cursor` to read the next page. * **Kind:** read * **Authorization:** `compute:images:read` @ `compute-tenant` + items * **Module:** `provision` * **Phase:** v0.2 (registered) **Input** | Field | Type | Required | Constraints | | ---------- | ---------------------- | -------- | ---------------------------------------------------------- | | `tenantId` | string | yes | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$` | | `kind` | one of `os`, `ramdisk` | | | | `limit` | integer | | 1-200; default `50` | | `cursor` | string | | at most 256 characters | ## promote [#promote] `POST /api/compute/images/promote` Makes a verified image the tenant owns public, so every tenant can read and deploy it. Decided as `compute:images:publish` on the image. An unsigned image is `INVALID_STATE`; an image the tenant does not own is `NOT_FOUND`. Promoting an image that is already public returns it unchanged. Site agents whose pools pre-warm this ref get their desired state refreshed. * **Kind:** mutation * **Authorization:** `compute:images:publish` @ `compute-image` * **Module:** `provision` * **Phase:** v0.2 (registered) **Input** | Field | Type | Required | Constraints | | ---------- | ------ | -------- | ---------------------------------------------------------------- | | `tenantId` | string | yes | at most 128 characters; matches `^[A-Za-z0-9._:-]{1,128}$` | | `imageId` | string | yes | at most 56 characters; matches `^img_[0-9a-hjkmnp-tv-z]{26,52}$` |