GET /api/images

List cloud images already cached on this Lite host.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/images

read

List cloud images already cached on this Lite host.

Use your host URL and API key as shell variables:

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

cURL template

curl --request GET "${baseUrl}/api/images" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.

Response

Returns an array of cached image objects.

Field	Type	Description
image_id	string	Stable cache id used by POST /api/vms.image.image_id.
sha256	string	SHA-256 digest of the cached image file.
size_bytes	integer	Size of the cached file on disk.
path	string	Absolute path on the Lite host. Use this as disk.base_path only from trusted automation.
distro	string	Normalized distro label, or an empty string when unknown.

Examples

Call example

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

curl "${baseUrl}/api/images" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Response example

[
  {
    "image_id": "debian-13-x86_64",
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "size_bytes": 8589934592,
    "path": "/var/lib/virtainer/images/debian-13-x86_64.qcow2",
    "distro": "debian"
  }
]

Errors

Status	Code	Description
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	API key is valid but not allowed to access the endpoint.
500	INTERNAL or STORAGE_ERROR	The host could not read the image cache.