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

type

string

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

range

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"
    }
  ]
}

data

EnrichedMonitor[]

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

Show EnrichedMonitor fields

string

Unique monitor ID (UUID).

name

string

Display name of the monitor.

type

string

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

config

object

Type-specific configuration. See Monitor config by type.

status

string

Current status. See Monitor statuses.

enabled

boolean

Whether the monitor is actively running checks.

latestResult

object | null

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

Show latestResult fields

status

string

Status from the last check.

latencyMs

number | null

Round-trip latency in milliseconds, if applicable.

createdAt

string

ISO 8601 timestamp of the check.

uptime

string | null

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

history

object[]

Bucketed status history for the selected range.

Show history item fields

status

string

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

label

string

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

createdAt

string

ISO 8601 creation timestamp.

updatedAt

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

name

string

required

Display name for the monitor.

type

string

required

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

config

object

required

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

alertChannelIds

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
}

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

name

string

New display name.

config

object

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

enabled

boolean

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

alertChannelIds

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 }
}

data.paused

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

limit

number

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

cursor

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..."
}

data

CheckResult[]

Array of check result objects.

cursor

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

Overview

Endpoints

​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