Check

Overview

The v1/check endpoint enables checking monitored containers for available image updates by querying the registry for the latest digest (HTTP HEAD with GET fallback).

It does not download image layers and does not check against the configured image cooldown, as the cooldown functionality remains an apply-time gate for scheduled updates and /v1/update.

When no-pull is enabled globally or via the container label, the check inspects the local image cache only and does not contact the registry.

Include check in http-api-endpoints to enable this endpoint.

Configuration

Parameters

Image Name

The image parameter filters the check to only include containers running specific image names.

curl -X POST -H "Authorization: Bearer mytoken" "localhost:8080/v1/check?image=foo/bar:1.0"

Container Name

The container parameter filters the check to only include specific containers by container name.

curl -X POST -H "Authorization: Bearer mytoken" "localhost:8080/v1/check?container=nginx"

Timeout

The timeout parameter overrides the per-request timeout for this check. It accepts Go durations such as 30s, 2m, or 5m. The value is capped by the configured check API timeout (--http-api-check-timeout / WATCHTOWER_HTTP_API_CHECK_TIMEOUT, default 5m).

curl -X POST -H "Authorization: Bearer mytoken" "localhost:8080/v1/check?timeout=2m"

Response Format

The /v1/check endpoint returns a JSON array of container check results:

{
    "containers": [
        {
            "name": "nginx",
            "image": "nginx:latest",
            "image_id": "sha256:abc...",
            "digest": "sha256:old...",
            "update_available": true,
            "latest_image_id": "",
            "latest_digest": "sha256:new...",
            "timestamp": "2025-01-20T11:30:45Z"
        }
    ],
    "count": 1,
    "timestamp": "2025-01-20T11:30:45Z",
    "api_version": "v1"
}

• name: Container name
• image: Current image reference with tag
• image_id: Current local image ID
• digest: Current local registry digest when known
• update_available: Whether a newer image is available
• latest_image_id: Local image ID of the newer image when known (often empty for registry digest checks that do not pull)
• latest_digest: Newest registry digest when known
• error: Per-container error message when the check failed

HTTP Status Codes

SSE Events

When the /v1/events SSE endpoint is also enabled, execution of the v1/check endpoint broadcasts the following events:

• scan_started: Broadcasted before the check begins
• scan_completed: Broadcasted after the check finishes successfully
• scan_failed: Broadcasted if the check encounters an error