HTTP API

Configuration

HTTP API

Deprecation Notice

Watchtower v2 Legacy HTTP API Configuration Deprecation

Endpoint-specific configuration options will be removed with the release of Watchtower v2.

Use the HTTP API Endpoints configuration option instead.

HTTP API Host

Sets the host interface for binding the HTTP API.

            Argument: --http-api-host
Environment Variable: WATCHTOWER_HTTP_API_HOST
                Type: String
             Default: empty (binds to all interfaces)

See the HTTP API Host documentation for details

HTTP API Port

Sets the listening port for the HTTP API.

            Argument: --http-api-port
Environment Variable: WATCHTOWER_HTTP_API_PORT
                Type: String
             Default: 8080

See the HTTP API Port documentation for details

HTTP API Token

Sets an authentication token for HTTP API requests.

            Argument: --http-api-token
Environment Variable: WATCHTOWER_HTTP_API_TOKEN
                Type: String
             Default: None

Supports file path for Docker Secrets (e.g., /run/secrets/http_api_token).

HTTP API Events Token

Sets an authentication token with read-only permissions specifically for the events SSE endpoint (/v1/events).

            Argument: --http-api-events-token
Environment Variable: WATCHTOWER_HTTP_API_EVENTS_TOKEN
                Type: String
             Default: None

This is a separate token from the http-api-token in order to reduce credential exposure, because events tokens may be exposed in URL query parameters.

The token can be provided via the Authorization header (for programmatic clients) or as the access_token query parameter (for browser EventSource which cannot set custom headers).

Events token leakage risk

When using the access_token query parameter (required for browser EventSource), the token appears in browser history, proxy logs, and access logs. This is a lower exposure than the main API token, but you should still treat the events token as a secret and rotate it if it has been exposed. Prefer header-based auth when possible.

This is required when the events endpoint is enabled via http-api-endpoints.

Supports file path for Docker Secrets (e.g., /run/secrets/http_api_events_token).

HTTP API Endpoints

Selects which HTTP API endpoints to enable.

            Argument: --http-api-endpoints
Environment Variable: WATCHTOWER_HTTP_API_ENDPOINTS
                Type: String (comma or space separated list)
             Default: empty (HTTP API disabled)

For more information, review the HTTP API documentation

Valid names (case-insensitive):

Name	Routes	Auth
`health`	`/livez`, `/readyz`, `/startupz`	None
`update`	`POST /v1/update`	`http-api-token`
`metrics`	`GET /v1/metrics`, `GET /v1/status`	`http-api-token`
`containers`	`GET /v1/containers`, `/v1/containers/details`	`http-api-token`
`check`	`POST /v1/check`	`http-api-token`
`history`	`GET /v1/history`	`http-api-token`
`images`	`GET /v1/images`	`http-api-token`
`config`	`GET /v1/config`	`http-api-token`
`events`	`GET /v1/events`	`http-api-events-token`
`swagger`	`GET /swagger/*`	None

Protected /v1/* endpoints require configuring a http-api-token.
Enabling events requires configuring a http-api-events-token.
The all value enables every endpoint and MUST be the only value.
Watchtower will exit on startup if an incorrect name is used or combined with all.

Flag and environment value usage

The CLI flag can be specified multiple times.
Defining the environment variable multiple times will not work (only the last value is used).
For environment variables use comma or space-separated values.

HTTP API Rate Limit

Sets the maximum number of API requests allowed per minute per IP address.

            Argument: --http-api-rate-limit
Environment Variable: WATCHTOWER_HTTP_API_RATE_LIMIT
                Type: Integer
             Default: 60

When the limit is exceeded, the client receives HTTP 429 (Too Many Requests).

HTTP API Check Timeout

Sets the maximum duration for the /v1/check API endpoint.

            Argument: --http-api-check-timeout
Environment Variable: WATCHTOWER_HTTP_API_CHECK_TIMEOUT
                Type: Duration
             Default: 5m

The /v1/check endpoint queries registries for the latest image digest. Increase this timeout if you see context deadline exceeded errors during checks.

HTTP API Update Timeout

Sets the maximum duration for the /v1/update API endpoint.

            Argument: --http-api-update-timeout
Environment Variable: WATCHTOWER_HTTP_API_UPDATE_TIMEOUT
                Type: Duration
             Default: 10m

The /v1/update endpoint performs a full container update scan. Increase this timeout if you see context deadline exceeded errors during updates.

HTTP API TLS Certificate

Path to the TLS certificate file for the HTTP API.

            Argument: --http-api-tls-cert
Environment Variable: WATCHTOWER_HTTP_API_TLS_CERT
                Type: String
             Default: empty (HTTP)

When both the http-api-tls-cert and http-api-tls-key are provided, the server uses HTTPS.

HTTP API TLS Key

Path to the TLS private key file for the HTTP API.

            Argument: --http-api-tls-key
Environment Variable: WATCHTOWER_HTTP_API_TLS_KEY
                Type: String
             Default: empty (HTTP)

When both the http-api-tls-cert and http-api-tls-key are provided, the server uses HTTPS.

See the HTTP API Host documentation for details

HTTP API Trusted Proxies

Comma-separated list of trusted proxy IP addresses or CIDR ranges for reverse proxy support. When set, enables proxy header processing for client IP and scheme detection.

            Argument: --http-api-trusted-proxies
Environment Variable: WATCHTOWER_HTTP_API_TRUSTED_PROXIES
                Type: String Array
             Default: (unset)

Required for correct client IP detection and rate limiting behind a reverse proxy (Traefik, Caddy, Nginx, etc.).

HTTP API Proxy Header

Header to read the real client IP from when behind a reverse proxy.

            Argument: --http-api-proxy-header
Environment Variable: WATCHTOWER_HTTP_API_PROXY_HEADER
                Type: String
             Default: X-Forwarded-For

Only used when http-api-trusted-proxies is set.

Common values:

X-Forwarded-For (Traefik, Caddy)
X-Real-IP (Nginx)
CF-Connecting-IP (Cloudflare)

HTTP API CORS Origins

Comma-separated list of allowed CORS origins for cross-origin requests. Use this to restrict which origins can access the API.

            Argument: --http-api-cors-origins
Environment Variable: WATCHTOWER_HTTP_API_CORS_ORIGINS
                Type: String Array
             Default: Unset (same-origin only)

When unset, CORS is disabled and only same-origin requests are allowed. Set this to permit specific cross-origin origins.

Deprecated Configuration Options

/// details | The following legacy configuration options are deprecated and will be removed with the release of Watchtower v2. type: warning

HTTP API Containers

Runs Watchtower with the read-only containers API enabled.

            Argument: --http-api-containers
Environment Variable: WATCHTOWER_HTTP_API_CONTAINERS
                Type: Boolean
             Default: false

Add containers to the http-api-endpoints configuration instead.

For example: WATCHTOWER_HTTP_API_ENDPOINTS=containers

HTTP API Metrics

Runs Watchtower with the Prometheus metrics API enabled.

            Argument: --http-api-metrics
Environment Variable: WATCHTOWER_HTTP_API_METRICS
                Type: Boolean
             Default: false

Add metrics to the http-api-endpoints configuration instead.

For example: WATCHTOWER_HTTP_API_ENDPOINTS=metrics

HTTP API Update

Runs Watchtower in HTTP API mode, so that image updates must be triggered by a request.

            Argument: --http-api-update
Environment Variable: WATCHTOWER_HTTP_API_UPDATE
                Type: Boolean
             Default: false

Add update to the http-api-endpoints configuration instead.

For example: WATCHTOWER_HTTP_API_ENDPOINTS=update

///

Last updated on August 13, 2026

Notifications