Docs
Catalog

List images

GET
/v1/images

Lists the image versions your org can create instances from, by family and then newest version first: those that are active or deprecated. Each version has one artifact per TEE, with its digest, the sizes it runs on and its signed reference manifest, and a launch contract that says what a create must supply: the disks, the access mode, the init-data formats and the minimum memory. An artifact appears once it passes the platform's boot test on its TEE, and it lists a GPU size only once its image passes GPU acceptance with that many GPUs.

image: "<family>" in a create resolves to the family's newest active version; image: "<family>@<version>" pins one. Until a new version has passed the boot test on a TEE, creates on that TEE that name the family get the newest active version that has, or if none has, the newest deprecated version still accepting creates that has; when no host with room has booted that one, the version before it. Among those versions, the newest that sells the create's size comes first, so a version that does not sell the size yet leaves its creates on the one before it. A version none of whose artifacts has passed is not listed. A deprecated version still runs its instances and accepts creates until createsEndAt; after that it is retired and no longer listed. A version withdrawn for a security flaw is retired the same day, and every org with an instance on it is told. Those instances keep running unless the flaw endangers their host or other tenants; then the platform stops them after notice, and they become failed with reason image_unavailable. A version that is not yet active does not exist for your org: a create that names it returns 400 invalid_request with violation not_found at /image. A create that names a retired version returns the same error with violation retired, and its message names the family's newest version.

Authorization

headerAuthorizationBearer <cc_...>

An API key of your org, sent as Authorization: Bearer cc_.... Keys start with cc_ and are otherwise opaque. Treat a key as a password: anyone holding it can act with its scopes until it expires or is revoked. Each operation's security requirement lists the scopes it needs; an empty list means any valid key. The MCP server at /mcp accepts agent keys and no other kind.

Query Parameters

pageSize?integer

The most items to return.

Range1 <= value <= 100
Default50
pageToken?string

The nextPageToken of the previous page, unchanged. Send the same filters with it.

Length1 <= length <= 2048

Header Parameters

Api-Version*string

The API version the request is written against. This document describes 2026-10-15. A missing header returns 400 api_version_required, and a version the API does not serve returns 400 unsupported_api_version.

X-Correlation-ID?string

An id of your own for this request, or for a group of requests, to find them in our logs and yours. Logged with the request and returned unchanged in X-Correlation-ID. The request id itself is always the API's own, in X-Request-ID.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin keys only: the id of the org to act in. Required with an admin key, together with Access-Reason; with any other credential it returns 400 invalid_request. Every request that carries it is recorded in that org's operator-access log.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin keys only: why the operator is acting in the org, such as a support ticket. Required with Org-Context. Recorded, verbatim, in the org's operator-access log.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Response Body

A page of image versions.

application/json
  1. response
items*array<>
nextPageToken?NextPageToken

Pass it back as pageToken for the next page. Absent on the last page.

Example Request
curl -X GET 'https://api.cloud.confidential.ai/v1/images?pageSize=50&pageToken=eyJjIjoiMjAyNi0xMC0yMlQxNzowMjoxMVoiLCJpIjoiaS03azJtOXE0eDFiZmEifQ' \  -H 'Api-Version: 2026-10-15' \  -H 'X-Correlation-ID: rollout-2026-10-22' \  -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed'
Example Response

The two v1 image families. Every artifact is TDX and lists CPU sizes only, because no image has passed GPU acceptance yet.

{  "items": [    {      "family": "c8s-node",      "version": "2026.10.1",      "status": "active",      "description": "A c8s Kubernetes node that joins the cluster its signed launch document names.",      "releasedAt": "2026-10-14T09:00:00Z",      "artifacts": [        {          "tee": "tdx",          "digest": "sha256:982a8305d97e901e472678751f00d86c5db63baf65386d815d00e0d6c5487ba1",          "sizes": [            "c1.4x",            "c1.8x",            "c1.16x",            "s1.2x",            "s1.4x",            "s1.8x",            "s1.16x",            "m1.2x",            "m1.4x",            "m1.8x"          ],          "referenceManifest": {            "uri": "https://measurements.example/c8s-node/2026.10.1/tdx/manifest.json",            "digest": "sha256:f39fd2c06953c22cc4f5c65815dc4aa5bc2dc24796969c5e8e5586c4e75761dd",            "logEntry": "rekor:1293911"          }        }      ],      "launch": {        "access": "launchKey",        "initDataFormats": [          "c8s-launch/v1"        ],        "userData": false,        "containers": false,        "gpuMetrics": false,        "attestationPort": 8443,        "attestationPublic": false,        "readiness": {          "tcpPorts": []        },        "minMemoryGiB": 8,        "disks": [          {            "name": "data",            "type": "scratch",            "required": true,            "minSizeGiB": 64,            "encryption": "guest",            "persistent": false          },          {            "name": "containerd",            "type": "scratch",            "required": false,            "minSizeGiB": 20,            "encryption": "guest",            "persistent": false          }        ]      }    },    {      "family": "confos-cpu",      "version": "2026.10.2",      "status": "active",      "description": "General-purpose Linux with Docker and containerd, reached over SSH.",      "releasedAt": "2026-10-20T09:00:00Z",      "artifacts": [        {          "tee": "tdx",          "digest": "sha256:8c780b3655fc55a663ed38174927e149157c6d2bedf81b9ce60a0a6d8ec33947",          "sizes": [            "c1.2x",            "c1.4x",            "c1.8x",            "c1.16x",            "s1.2x",            "s1.4x",            "s1.8x",            "s1.16x",            "m1.2x",            "m1.4x",            "m1.8x"          ],          "referenceManifest": {            "uri": "https://measurements.example/confos-cpu/2026.10.2/tdx/manifest.json",            "digest": "sha256:472d2826575f5b45c0b463738780a3200de086f98737e7b5bf5298b02a475308",            "logEntry": "rekor:1293847"          }        }      ],      "launch": {        "access": "sshKeys",        "initDataFormats": [],        "userData": false,        "containers": false,        "gpuMetrics": false,        "attestationPort": 8400,        "attestationPublic": true,        "readiness": {          "tcpPorts": [            8400          ]        },        "minMemoryGiB": 4,        "disks": [          {            "name": "data",            "type": "scratch",            "required": false,            "minSizeGiB": 10,            "encryption": "guest",            "persistent": false          },          {            "name": "user-data",            "type": "scratch",            "required": true,            "minSizeGiB": 10,            "encryption": "none",            "persistent": true          }        ]      }    },    {      "family": "confos-cpu",      "version": "2026.09.3",      "status": "deprecated",      "description": "General-purpose Linux with Docker and containerd, reached over SSH.",      "releasedAt": "2026-09-29T09:00:00Z",      "createsEndAt": "2026-11-20T00:00:00Z",      "artifacts": [        {          "tee": "tdx",          "digest": "sha256:933b1d6f3ad2716e3dc325803660a8bef3107a0fdb3796fdeb858bc187d7bfdd",          "sizes": [            "c1.2x",            "c1.4x",            "c1.8x",            "c1.16x",            "s1.2x",            "s1.4x",            "s1.8x",            "s1.16x",            "m1.2x",            "m1.4x",            "m1.8x"          ],          "referenceManifest": {            "uri": "https://measurements.example/confos-cpu/2026.09.3/tdx/manifest.json",            "digest": "sha256:c9a3168c6fd6431a3ee471c5ae5813e3f948cd15212188c5fd4fe0bd22950cf4",            "logEntry": "rekor:1180234"          }        }      ],      "launch": {        "access": "sshKeys",        "initDataFormats": [],        "userData": false,        "containers": false,        "gpuMetrics": false,        "attestationPort": 8400,        "attestationPublic": true,        "readiness": {          "tcpPorts": [            8400          ]        },        "minMemoryGiB": 4,        "disks": [          {            "name": "data",            "type": "scratch",            "required": false,            "minSizeGiB": 10,            "encryption": "guest",            "persistent": false          },          {            "name": "user-data",            "type": "scratch",            "required": true,            "minSizeGiB": 10,            "encryption": "none",            "persistent": true          }        ]      }    }  ]}