Skip to content
Overwatch API

Register an uptime monitor

POST
/v1/sites/{id}/uptime/monitors
curl --request POST \
  --url https://api.overwatch.weareheavy.dev/v1/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/uptime/monitors \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "url": "https://example.com/health", "name": "API health", "cadenceSeconds": 60, "alertEmails": [ "oncall@example.com" ], "alertWebhooks": [ { "kind": "slack", "url": "https://hooks.slack.com/services/T000/B000/XXXX" } ] }'

Register a monitor: the URL is probed from four regions (North America, Europe, Asia, Oceania) on the chosen cadence, and a first probe from every region fires immediately. Requires an owner/admin session or an API key; the Uptime app must be enabled for the site.

Monitors count against an allowance (2 included per site); past it, creation requires overage billing and fails with 403 otherwise.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
string format: uuid

The site’s UUID.

Request Bodyrequired

Section titled “ Request Bodyrequired ”
Media typeapplication/json

Mutable monitor fields. url is required on create; on update every field is optional and omitted fields keep their current value.

object
url

The http(s) URL to probe.

string format: uri
name

A display name; null shows the URL.

string | null
<= 100 characters
cadenceSeconds

How often each region probes the URL.

integer
default: 60
Allowed values: 60 300 900 1800 3600
timeoutSeconds

Probe request timeout; a slower probe counts as failed.

integer
default: 10 >= 1 <= 30
enabled

false pauses probing without deleting the monitor or its history.

boolean
default: true
alertEmails

Extra alert addresses for this monitor, on top of the notification settings.

Array<string>
<= 10 items
alertWebhooks

Extra alert webhooks for this monitor.

Array<object>
<= 5 items

A notification webhook. slack, discord, and teams format the message for the respective chat app; http POSTs a structured JSON payload to any endpoint.

object
kind
required
string
Allowed values: slack discord teams http
url
required
string format: uri
Example
{
  "url": "https://example.com/health",
  "name": "API health",
  "cadenceSeconds": 60,
  "alertEmails": [
    "oncall@example.com"
  ],
  "alertWebhooks": [
    {
      "kind": "slack",
      "url": "https://hooks.slack.com/services/T000/B000/XXXX"
    }
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

The new monitor. Probing starts immediately when enabled.

Media typeapplication/json
object
monitor
required

A stored uptime monitor. status/status_since double as current status.

object
id
required
string format: uuid
tenant_id
required
string
site_id
required
string format: uuid
url
required
string format: uri
name
required
string | null
cadence_seconds
required
integer
timeout_seconds
required
integer
enabled
required
integer
Allowed values: 0 1
alert_emails
required

JSON-encoded array of extra alert addresses.

string | null
alert_webhooks
required

JSON-encoded array of extra alert webhooks.

string | null
status
required

Consensus status written by the coordinator; unknown before the first probes.

string
Allowed values: up degraded down unknown
status_since
required

Epoch ms the current status began, or null.

integer | null
last_checked_at
required

Epoch ms of the last probe, or null.

integer | null
created_at
required
integer
updated_at
required
integer
Example
{
  "monitor": {
    "enabled": 0,
    "status": "up"
  }
}

400

Section titled “ 400 ”

url is missing or a field failed validation.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "cadenceSeconds must be one of 60, 300, 900, 1800, 3600"
}

401

Section titled “ 401 ”

Missing or invalid credentials.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "invalid api key"
}

403

Section titled “ 403 ”

The caller may not manage monitors, or the included monitors are in use and overage billing is off.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "this site's 2 included monitors are in use — enable overage billing on the Billing page to add more"
}

404

Section titled “ 404 ”

No site with that id is visible to the caller.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "site not found"
}

409

Section titled “ 409 ”

The Uptime app is not enabled for this site.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "uptime is not enabled for this site"
}