GET /api/registry/images

List registry images visible to this Lite host.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/registry/images

read

Read the image catalog visible to 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/registry/images" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.
Query	distro	string	no	Filter by distro, such as debian or fedora.
Query	version	string	no	Filter by distro version.
Query	latest	boolean	no	When true, only return images marked latest by the registry.

Response

Returns an array of registry image objects.

Field	Type	Description
id	string	Opaque registry image id. Use with GET /api/registry/images/{id}.
distro	string	Distro label.
version	string	Distro version.
arch	string	CPU architecture, such as x86_64.
release_id	string	Upstream release identifier.
filename	string	Source image filename.
download_url	string	URL the Lite host can fetch when creating or caching the image.
checksum_algo	string	Checksum algorithm, usually sha256 or sha512.
checksum	string	Expected checksum value.
file_size	integer or null	Size in bytes when known.
is_latest	boolean	Whether this is the latest enabled image for its distro/version group.
source	string	Registry ingestion source.
enabled	boolean	Whether this image is enabled in the registry.
discovered_at	string	Registry discovery timestamp.
created_at	string	Registry record creation timestamp.

Examples

Call example

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

curl "${baseUrl}/api/registry/images?distro=debian&latest=true" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Response example

[
  {
    "id": "debian-13-x86_64-20260703",
    "distro": "debian",
    "version": "13",
    "arch": "x86_64",
    "release_id": "20260703",
    "filename": "debian-13-x86_64.qcow2",
    "download_url": "https://images.example.com/debian-13-x86_64.qcow2",
    "checksum_algo": "sha256",
    "checksum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "file_size": 8589934592,
    "is_latest": true,
    "source": "public-registry",
    "enabled": true,
    "discovered_at": "2026-07-03T10:00:00Z",
    "created_at": "2026-07-03T10:00:00Z"
  }
]

Errors

Status	Code	Description
400	BAD_REQUEST	Image registry is not configured on the Lite host.
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	API key is valid but not allowed to access the endpoint.
500	STORAGE_ERROR	Registry request or response parsing failed.