Monitors API: create, list, update, and delete monitors

Monitors are the core resource in Overwatch. Each monitor represents a single check — an HTTP endpoint, TCP port, TLS certificate, DNS record, or scheduled job — that your workers run on a recurring interval. This page covers every monitor endpoint: listing, creating, reading, updating, deleting, pausing, and retrieving historical check results.

List monitors

GET /api/v1/monitors

Returns all monitors in your organization, enriched with uptime percentage, the latest check result, and a bucketed status history for the selected time range.

Query parameters

string

Filter monitors by type. One of HTTP, TCP, TLS, DNS, SCHEDULED. Omit to return all types.

string

Time range for the history buckets and uptime calculation. One of 1d, 7d, 30d, 90d. Defaults to 90d. Uptime percentage is always computed over the trailing 90 days regardless of this value.

Response

{
  "data": [
    {
      "id": "mon_01j...",
      "name": "API health",
      "type": "HTTP",
      "config": { "url": "https://api.example.com/health", "interval": 60 },
      "status": "up",
      "enabled": true,
      "latestResult": {
        "status": "up",
        "latencyMs": 142,
        "createdAt": "2025-04-15T10:00:00.000Z"
      },
      "uptime": "99.87%",
      "history": [
        { "status": "up", "label": "Apr 13–14" },
        { "status": "degraded", "label": "Apr 14–15" }
      ],
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-04-15T10:00:00.000Z"
    }
  ]
}

EnrichedMonitor[]

Array of monitor objects. Each object includes all monitor fields plus enrichment.

Show EnrichedMonitor fields

string

Unique monitor ID (UUID).

string

Display name of the monitor.

string

Monitor type: HTTP, TCP, TLS, DNS, or SCHEDULED.

object

Type-specific configuration. See Monitor config by type.

string

Current status. See Monitor statuses.

boolean

Whether the monitor is actively running checks.

object | null

The most recent check result within the selected range, or null if none exists.

Show latestResult fields

string

Status from the last check.

number | null

Round-trip latency in milliseconds, if applicable.

string

ISO 8601 timestamp of the check.

string | null

Uptime percentage over the trailing 90 days, e.g. "99.87%". null if there are no results yet.

object[]

Bucketed status history for the selected range.

Show history item fields

string

Worst status observed in that bucket, or unknown if no checks ran.

string

Human-readable label for the time bucket, e.g. "Apr 7–8".

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

Example

curl https://overwatchapp.dev/api/v1/monitors?type=HTTP&range=7d \
  -H "Authorization: Bearer $API_KEY"

Create a monitor

POST /api/v1/monitors

Creates a new monitor. Requires admin or owner role. Returns 402 if your organization has no active subscription, and 422 with "upgrade": true if you have reached your monitor limit.

Request body

string

required

Display name for the monitor.

string

required

Monitor type. One of HTTP, TCP, TLS, DNS, SCHEDULED.

object

required

Type-specific configuration object. See Monitor config by type below.

string[]

Optional list of alert channel IDs to bind to this monitor. Alerts fire on status changes.

Monitor config by type

{
  "url": "https://api.example.com/health",
  "interval": 60
}

{
  "host": "db.example.com",
  "port": 5432,
  "interval": 60
}

{
  "host": "example.com",
  "port": 443,
  "interval": 300
}

{
  "hostname": "example.com",
  "interval": 300
}

{
  "interval": 300
}

For SCHEDULED monitors, the interval field in config is always set to 300 seconds regardless of what you submit. The interval for scheduled job monitors is determined by how often your job calls the checkin URL — not by the config.

Monitor statuses

The statuses a monitor can report depend on its type:

Type	Possible statuses
`HTTP`	`up`, `down`, `degraded`
`TCP`	`up`, `down`, `degraded`
`TLS`	`active`, `expiring_soon`, `expired`, `no_cert`
`DNS`	`present`, `missing`, `changed`
`SCHEDULED`	`ok`, `failed`, `havent_heard`

Response

Returns 201 Created with the new monitor object. For SCHEDULED monitors, the response also includes a checkinUrl field — the public URL your cron job should call to register a successful run.

{
  "data": {
    "id": "mon_01j...",
    "name": "Nightly export job",
    "type": "SCHEDULED",
    "config": { "interval": 300 },
    "status": "unknown",
    "enabled": true,
    "checkinUrl": "https://overwatchapp.dev/api/v1/monitors/mon_01j.../checkin",
    "createdAt": "2025-04-15T10:00:00.000Z",
    "updatedAt": "2025-04-15T10:00:00.000Z"
  }
}

Example

curl -X POST https://overwatchapp.dev/api/v1/monitors \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API health",
    "type": "HTTP",
    "config": { "url": "https://api.example.com/health", "interval": 60 },
    "alertChannelIds": ["alc_01j..."]
  }'

Get a monitor

GET /api/v1/monitors/:id

Returns a single monitor by ID, including its bound alert channels.

Path parameters

string

required

The monitor ID.

Response

{
  "data": {
    "id": "mon_01j...",
    "name": "API health",
    "type": "HTTP",
    "config": { "url": "https://api.example.com/health", "interval": 60 },
    "status": "up",
    "enabled": true,
    "alertBindings": [
      {
        "monitorId": "mon_01j...",
        "alertChannelId": "alc_01j..."
      }
    ],
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-04-15T10:00:00.000Z"
  }
}

Example

curl https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $API_KEY"

Update a monitor

PATCH /api/v1/monitors/:id

Updates one or more fields on a monitor. All fields are optional — only the fields you include are changed. Requires admin or owner role. When you supply alertChannelIds, the full list of bindings is replaced with the new set. Pass an empty array ([]) to remove all alert bindings.

Path parameters

string

required

The monitor ID.

Request body

string

New display name.

object

Updated type-specific configuration. For SCHEDULED monitors, interval is always forced to 300.

boolean

Set to false to pause this monitor, true to resume it.

string[]

Replaces the monitor’s alert channel bindings with this list.

Response

Returns the updated monitor object with 200 OK.

Example

curl -X PATCH https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Delete a monitor

DELETE /api/v1/monitors/:id

Permanently deletes a monitor and all associated check results. Requires admin or owner role.

Path parameters

string

required

The monitor ID.

Response

{
  "data": { "id": "mon_01j..." }
}

Example

curl -X DELETE https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $API_KEY"

Pause all monitors

POST /api/v1/monitors/pause-all

Sets enabled: false on every currently-enabled monitor in your organization. Useful as an emergency kill switch during deployments or incidents. Requires admin or owner role.

Response

Returns the count of monitors that were paused.

{
  "data": { "paused": 12 }
}

number

The number of monitors that were paused by this request. Monitors that were already disabled are not counted.

Example

curl -X POST https://overwatchapp.dev/api/v1/monitors/pause-all \
  -H "Authorization: Bearer $API_KEY"

Get check results for a monitor

GET /api/v1/monitors/:id/results

Returns paginated check results for a single monitor, ordered most-recent first.

Path parameters

string

required

The monitor ID.

Query parameters

number

Number of results to return. Maximum 200, default 50.

string

Cursor from a previous response to fetch the next page.

Response

{
  "data": [
    {
      "id": "res_01j...",
      "monitorId": "mon_01j...",
      "status": "up",
      "latencyMs": 137,
      "detail": null,
      "alertTriggered": false,
      "alertOutcome": null,
      "createdAt": "2025-04-15T10:00:00.000Z"
    }
  ],
  "cursor": "res_01j..."
}

CheckResult[]

Array of check result objects.

string | null

Pass this value as ?cursor= in your next request to fetch the following page. null when there are no more results.

Example

curl "https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID/results?limit=100" \
  -H "Authorization: Bearer $API_KEY"

Overview

Endpoints

Monitors API: create, list, update, and delete monitors

List monitors

Query parameters

Response

Example

Create a monitor

Request body

Monitor config by type

Monitor statuses

Response

Example

Get a monitor

Path parameters

Response

Example

Update a monitor

Path parameters

Request body

Response

Example

Delete a monitor

Path parameters

Response

Example

Pause all monitors

Response

Example

Get check results for a monitor

Path parameters

Query parameters

Response

Example

​List monitors

​Query parameters

​Response

​Example

​Create a monitor

​Request body

​Monitor config by type

​Monitor statuses

​Response

​Example

​Get a monitor

​Path parameters

​Response

​Example

​Update a monitor

​Path parameters

​Request body

​Response

​Example

​Delete a monitor

​Path parameters

​Response

​Example

​Pause all monitors

​Response

​Example

​Get check results for a monitor

​Path parameters

​Query parameters

​Response

​Example

List monitors

Query parameters

Response

Example

Create a monitor

Request body

Monitor config by type

Monitor statuses

Response

Example

Get a monitor

Path parameters

Response

Example

Update a monitor

Path parameters

Request body

Response

Example

Delete a monitor

Path parameters

Response

Example

Pause all monitors

Response

Example

Get check results for a monitor

Path parameters

Query parameters

Response

Example