Skip to content
API
Overview

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

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.

  • !!! 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