Overview

Watchtower has an optional HTTP API server that is enabled by configuring the http-api-endpoints and http-api-token configuration options and publishing the HTTP API port (default: 8080).

This HTTP API server extends Watchtower’s functionality by providing HTTP endpoints that allows for programmatic access to functionality, such as checking the current status of monitored containers and requesting Watchtower to perform container updates. Parameters, such as container and image name filters, can be used to further fine-tune HTTP requests.

Deprecation of HTTP API Endpoint Configuration Options

The following options have been deprecated in favor of the unified http-api-endpoints configuration option and will be removed with the v2.x.x release of Watchtower:

Endpoints

The following endpoints can be enabled by using thehttp-api-endpoints configuration option and the respective configuration value.

Name	Configuration Value	Method	Endpoint	Auth	Parameters	Description
Update	`update`	`POST`	`/v1/update`	API token	`image`, `container`, `async`	Triggers container updates and returns JSON results of the operation
Check	`check`	`POST`	`/v1/check`	API token	`image`, `container`	Checks containers for available updates via registry digest query
Containers	`containers`	`GET`	`/v1/containers`	API token	`name`, `image`	Lists watched containers and their current running image digests
Container Details	`containers`	`GET`	`/v1/containers/details`	API token	`name`, `image`	Returns detailed information about each watched container including running state and configuration flags
History	`history`	`GET`	`/v1/history`	API token	`since`, `until`, `limit`	Returns historical scan results from the in-memory ring buffer (up to 500 entries)
Images	`images`	`GET`	`/v1/images`	API token	`name`, `id`	Lists tracked images with their current digests and container counts
Config	`config`	`GET`	`/v1/config`	API token		Returns the active Watchtower configuration settings
Events	`events`	`GET`	`/v1/events`	Events token		Streams real-time operational events via Server-Sent Events
Status	`metrics`	`GET`	`/v1/status`	API token		Returns the summary of the most recent scan
Metrics	`metrics`	`GET`	`/v1/metrics`	API token		Exposes Prometheus-compatible metrics for monitoring and alerting
Swagger	`swagger`	`GET`	`/swagger/*`	None		Interactive API documentation via Swagger UI
Liveness	`health`	`GET`	`/livez`	None		Returns `200 OK` when the server is running
Readiness	`health`	`GET`	`/readyz`	None		Returns `200 OK` when Docker client is connected, `503` otherwise
Startup	`health`	`GET`	`/startupz`	None		Returns `200 OK` once the server has started

Endpoints enforce HTTP method restrictions using method-based routing.
Requests with unsupported methods will receive a 405 Method Not Allowed response.
Watchtower will not start if http-api-endpoints has incorrect values or is combined with all (which enables all endpoints).

Examples

services:
    watchtower:
        image: nickfedor/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            - WATCHTOWER_HTTP_API_ENDPOINTS=check
            - WATCHTOWER_HTTP_API_TOKEN=your-secure-token
        ports:
            - 8080:8080
        restart: unless-stopped

docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e WATCHTOWER_HTTP_API_ENDPOINTS=check \
    -e WATCHTOWER_HTTP_API_TOKEN=your-secure-token \
    -p 8080:8080 \
    --restart unless-stopped \
    nickfedor/watchtower

services:
    watchtower:
        image: nickfedor/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            - WATCHTOWER_HTTP_API_ENDPOINTS=update
            - WATCHTOWER_HTTP_API_TOKEN=your-secure-token
        ports:
            - 8080:8080
        restart: unless-stopped

docker run -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e WATCHTOWER_HTTP_API_ENDPOINTS=update \
    -e WATCHTOWER_HTTP_API_TOKEN=your-secure-token \
    -p 8080:8080 \
    --restart unless-stopped \
    nickfedor/watchtower

services:
    watchtower:
        image: nickfedor/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            - WATCHTOWER_HTTP_API_ENDPOINTS=swagger
            - WATCHTOWER_HTTP_API_TOKEN=your-secure-token
        ports:
            - 8080:8080
        restart: unless-stopped

docker run -d \
    --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -e WATCHTOWER_HTTP_API_ENDPOINTS=swagger \
    -e WATCHTOWER_HTTP_API_TOKEN=your-secure-token \
    -p 8080:8080 \
    --restart unless-stopped \
    nickfedor/watchtower

Security considerations

Watchtower was originally designed to be a stateless application with direct access to the Docker socket. By having direct access to the Docker socket, the application effectively runs with root-level privileges. It is worth taking a moment to review and familiarize yourself with the Docker Engine security documentation and explore other security tools such as Docker socket proxies.

!!! Warning “The HTTP API should never be directly exposed to the Internet!”
!!! Warning “Using the HTTP API without TLS encryption is insecure and not recommended!”
!!! Warning “Only enable the endpoints that you need!”

Authentication, TLS, trusted proxies, CORS, and rate limiting are covered under Authentication, TLS, and the HTTP API configuration reference.

Last updated on October 2, 2026