Images

Overview

The /v1/images/ endpoint lists the images tracked by Watchtower along with their current digests and container counts. Include images in http-api-endpoints to enable this read-only endpoint.

Response Format

The /v1/images endpoint returns a JSON object with image statuses:

{
    "images": [
        {
            "name": "nginx:latest",
            "image_id": "sha256:1111...",
            "digest": "sha256:2222...",
            "containers": 3
        }
    ],
    "count": 1,
    "timestamp": "2025-01-20T11:30:45Z",
    "api_version": "v1"
}

• name: Image name with tag
• image_id: Local image config ID (sha256:…)
• digest: Registry manifest digest (sha256:…). Empty for locally-built images.
• containers: Number of watched containers using this image

Parameters

Image Name

The name parameter filters results to a specific image by exact name.

curl -H "Authorization: Bearer mytoken" "localhost:8080/v1/images?name=nginx:latest"

Image ID

The id parameter filters results to a specific image by its image ID.

curl -H "Authorization: Bearer mytoken" "localhost:8080/v1/images?id=sha256:1111..."

HTTP Status Codes