Documentation

Watchtower API compatibility guide

This page explains the minimum contract a service should expose so Watchtower can poll it, classify its status, and show useful diagnostics in the dashboard.

TL;DR

Expose one fast, stable health endpoint, with GET /api/health as the default, that returns JSON with a common shape like { status: string, service: string, timestamp: string, version?: string, checks?: object }. Watchtower will poll it repeatedly and use the response to mark the service as up, degraded, or down.

Standard endpoint

Each service should expose one stable HTTP endpoint that returns the health state of the service.

  • Method: `GET`
  • Path: a predictable health endpoint such as `/health`, `/status`, or `/api/health`
  • Preferred default: `GET /api/health`.
  • Behavior: respond quickly and deterministically
  • Status code: `200` for healthy, non-`200` for unhealthy

Expected response body

Watchtower works best when the response is JSON and includes enough information to help developers understand what is failing. 

{
  "status": "up",
  "service": "orders-api",
  "timestamp": "2026-05-11T12:00:00.000Z",
  "version": "1.4.2",
  "checks": {
    "database": "up",
    "cache": "up"
  }
}
  • `status`: the canonical health value, typically `up`, `degraded`, or `down`
  • `service`: human-readable service name
  • `timestamp`: when the check was produced
  • `version`: optional build or release version
  • `checks`: optional component-level detail for debugging

Compatibility rules

  • Return JSON with a stable schema.
  • Keep latency low so polling does not create noise.
  • Use explicit failures for partial outages instead of always returning `200`.
  • Avoid secrets or private implementation details in the body.
  • Make the endpoint safe to poll repeatedly.

How Watchtower interprets the response

Watchtower reads the endpoint response, stores the latest result, and uses the HTTP status plus the returned health payload to show the service as healthy, degraded, or down in the dashboard. If your API already has a health endpoint, map it to this contract instead of introducing a custom one-off format.

For new services, start with one health endpoint, keep the payload small, and make the semantics explicit. That keeps Watchtower polling simple and reliable.