Developer Documentation

Overview

Watchtowers monitors your services by polling health check endpoints and displaying the results in a beautiful dashboard. Your API returns a simple JSON response, and Watchtowers renders it as service cards, metrics, and sparkline charts.

The schema is based on the IETF Health Check Response Format (application/health+json) with Watchtowers-specific extensions for rich visualization.

IETF Draft: draft-inadarei-api-health-check-06

Quick Start

At minimum, your health endpoint just needs to return a status field.

Watchtowers will display this as a simple status indicator showing your service health at a glance.

Accepted status values:

pass or "ok", "up", "healthy"

warn or "warning", "degraded"

fail or "error", "down", "unhealthy"

{
  "status": "pass"
}

Renders as:

Healthy

Services

Add a services array to display status cards for each component of your system.

Each service shows its status with a colored indicator, optional icon, and value.

Service object fields:

Field	Type	Required
`name`	string	✓
`status`	string	✓
`label`	string
`icon`	string
`value`	number
`badge`	string
`url`	string

{
  "status": "pass",
  "services": [
    {
      "name": "api",
      "icon": "globe",
      "status": "pass",
      "value": 3
    },
    {
      "name": "worker",
      "icon": "gearshape.2",
      "status": "pass",
      "value": 2
    },
    {
      "name": "redis",
      "icon": "cylinder",
      "status": "warn"
    }
  ]
}

Renders as service cards with status indicators

Metrics

Add a metrics array to display numeric values with optional sparkline charts.

The history array provides data points for the sparkline visualization.

Metric object fields:

Field	Type	Required
`name`	string	✓
`value`	number	✓
`label`	string
`history`	number[]
`color`	string
`url`	string

{
  "status": "pass",
  "metrics": [
    {
      "name": "requests",
      "label": "Requests/min",
      "value": 847,
      "history": [720, 750, 780, 800, 820, 830, 847],
      "color": "blue"
    },
    {
      "name": "errors",
      "label": "Errors",
      "value": 3,
      "history": [0, 1, 2, 1, 0, 2, 3],
      "color": "red"
    }
  ]
}

Renders as metric cards with sparkline charts

Complete Example

Combine services and metrics for a complete dashboard view.

This example shows a production API with web servers, workers, a scheduler, and Redis, along with usage metrics.

Tips:

• Services appear as status cards
• Metrics show values with sparklines
• Add URLs to make cards clickable
• Use 8-30 history points for best sparklines

{
  "status": "pass",
  "description": "Production API Health",
  "version": "2.1.0",
  "services": [
    { "name": "web", "label": "Web", "icon": "globe", "status": "pass", "value": 2 },
    { "name": "worker", "label": "Worker", "icon": "gearshape.2", "status": "pass", "value": 1 },
    { "name": "scheduler", "label": "Scheduler", "icon": "clock", "status": "pass" },
    { "name": "redis", "label": "Redis", "icon": "cylinder", "status": "pass" }
  ],
  "metrics": [
    {
      "name": "users_today",
      "label": "Users Today",
      "value": 142,
      "history": [80, 95, 110, 125, 130, 138, 142],
      "color": "blue"
    },
    {
      "name": "requests",
      "label": "Requests/min",
      "value": 847,
      "history": [720, 750, 780, 800, 820, 830, 847],
      "color": "purple"
    },
    {
      "name": "latency",
      "label": "Avg Latency",
      "value": 45,
      "history": [52, 48, 50, 47, 46, 44, 45],
      "color": "green"
    }
  ]
}

Reference

SF Symbol Icons

Use any SF Symbol name in the icon field.

globe

Web/API

gearshape.2

Workers

clock

Schedulers

cylinder

Databases

Browse all SF Symbols →

Color Names

Supported color names for the color field:

blue

purple

pink

red

orange

yellow

green

gray

Sparkline Charts

The history array renders as a mini line chart.

• Array order: oldest to newest
• 8-30 data points works best
• Values auto-scale

Example:

[10, 15, 12, 18, 25, 22, 30]

oldest

newest

Watchtowers Schema