GET /api/registry/images/{id}

Read one registry image record by image id.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/registry/images/${id}

read

Read one registry image record.

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/${id}" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.
Path	id	string	yes	Registry image id from GET /api/registry/images.

Response

Returns one registry image object.

Field	Type	Description
id	string	Opaque registry image 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>"
imageId="debian-13-x86_64-20260703"

curl "${baseUrl}/api/registry/images/${imageId}" \
  --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 failed, the id was not found upstream, or response parsing failed.