API & MCP

API reference

Generated from the OpenAPI spec, so it always matches what the API accepts. Base URL https://observe.live/api/v1. Send a token as a bearer token; read-only tokens get 403 on writes, and tokens limited to specific monitors get 403 on organization endpoints.

Errors: 401 no or bad token, 403 not allowed (role or token), 404 missing or not visible to you, 422 validation (errors keyed by field), 429 over 120 requests a minute. Lists are paginated with page (and per_page where shown) and return links and meta.

Public

GET /public-metrics Public product metrics (no token needed)

Returns 200 · object

Oh Dear compatible

GET /oh-dear/monitors Oh Dear listMonitors

Returns 200 · OhDearMonitor[]

POST /oh-dear/monitors Oh Dear createMonitor (type http only; team_id is an organization ID, a numeric one means your own)

Body (JSON)

url* string
type string one of http
team_id string | integer | null
friendly_name string | null
label string | null

Returns 201 · OhDearMonitor

GET /oh-dear/monitors/{monitor_id} Oh Dear getMonitor

Parameters

  • monitor_id (path, required) — Monitor ID

Returns 200 · OhDearMonitor

GET /oh-dear/monitors/{monitor_id}/uptime Oh Dear getUptime (split=hour covers at most 7 days)

Parameters

  • monitor_id (path, required) — Monitor ID
  • filter[started_at] (query, required) — YmdHis, UTC
  • filter[ended_at] (query, required) — YmdHis, UTC
  • split (query, required) — one of hour, day, month

Returns 200 · object[]

GET /oh-dear/monitors/{monitor_id}/downtime Oh Dear getDowntime

Parameters

  • monitor_id (path, required) — Monitor ID
  • filter[started_at] (query, required) — YmdHis, UTC
  • filter[ended_at] (query, required) — YmdHis, UTC

Returns 200 · object[]

POST /oh-dear/checks/{check_id}/request-run Oh Dear requestCheckRun

Parameters

  • check_id (path, required) — Check ID: {monitor_id}-uptime or {monitor_id}-certificate_health

Returns 200 · OhDearCheck

POST /oh-dear/checks/{check_id}/snooze Oh Dear snoozeCheck (snoozes every alert for the monitor)

Parameters

  • check_id (path, required) — Check ID: {monitor_id}-uptime or {monitor_id}-certificate_health

Body (JSON)

minutes* integer min 1; max 10080

Returns 200 · OhDearCheck

POST /oh-dear/checks/{check_id}/unsnooze Oh Dear unsnoozeCheck

Parameters

  • check_id (path, required) — Check ID: {monitor_id}-uptime or {monitor_id}-certificate_health

Returns 200 · OhDearCheck

Laravel schedule monitor

GET /schedule-monitor/{monitor_id}/monitors/{oh_dear_monitor_id} spatie/laravel-schedule-monitor: schedule-monitor:verify

Parameters

  • monitor_id (path, required) — Monitor ID
  • oh_dear_monitor_id (path, required) — Any number (OH_DEAR_MONITOR_ID, or OH_DEAR_SITE_ID on v3); the monitor comes from monitor_id

Returns 200 · object

POST /schedule-monitor/{monitor_id}/monitors/{oh_dear_monitor_id}/cron-checks/sync spatie/laravel-schedule-monitor: schedule-monitor:sync (replaces the monitor's tasks)

Parameters

  • monitor_id (path, required) — Monitor ID
  • oh_dear_monitor_id (path, required) — Any number (OH_DEAR_MONITOR_ID, or OH_DEAR_SITE_ID on v3); the monitor comes from monitor_id

Body (JSON)

cron_checks* object[] max items 200

Returns 200 · CronCheck[]

POST /schedule-monitor/{monitor_id}/monitors/{oh_dear_monitor_id}/cron-checks spatie/laravel-schedule-monitor: schedule-monitor:sync --keep-old (adds one task)

Parameters

  • monitor_id (path, required) — Monitor ID
  • oh_dear_monitor_id (path, required) — Any number (OH_DEAR_MONITOR_ID, or OH_DEAR_SITE_ID on v3); the monitor comes from monitor_id

Body (JSON)

name* string
type string one of cron
cron_expression* string
grace_time_in_minutes integer min 0; max 1440
server_timezone string | null
description string

Returns 201 · CronCheck

GET /schedule-monitor/{monitor_id}/sites/{oh_dear_monitor_id} spatie/laravel-schedule-monitor v3: schedule-monitor:verify

Parameters

  • monitor_id (path, required) — Monitor ID
  • oh_dear_monitor_id (path, required) — Any number (OH_DEAR_MONITOR_ID, or OH_DEAR_SITE_ID on v3); the monitor comes from monitor_id

Returns 200 · object

POST /schedule-monitor/{monitor_id}/sites/{oh_dear_monitor_id}/cron-checks/sync spatie/laravel-schedule-monitor v3: schedule-monitor:sync (replaces the monitor's tasks)

Parameters

  • monitor_id (path, required) — Monitor ID
  • oh_dear_monitor_id (path, required) — Any number (OH_DEAR_MONITOR_ID, or OH_DEAR_SITE_ID on v3); the monitor comes from monitor_id

Body (JSON)

cron_checks* object[] max items 200

Returns 200 · CronCheck[]

POST /schedule-monitor/{monitor_id}/sites/{oh_dear_monitor_id}/cron-checks spatie/laravel-schedule-monitor v3: schedule-monitor:sync --keep-old (adds one task)

Parameters

  • monitor_id (path, required) — Monitor ID
  • oh_dear_monitor_id (path, required) — Any number (OH_DEAR_MONITOR_ID, or OH_DEAR_SITE_ID on v3); the monitor comes from monitor_id

Body (JSON)

name* string
type string one of cron
cron_expression* string
grace_time_in_minutes integer min 0; max 1440
server_timezone string | null
description string

Returns 201 · CronCheck

Incidents

GET /monitors/{monitor_id}/incidents Incidents, newest first, with private team notes

Parameters

  • monitor_id (path, required) — Monitor ID

Returns 200 · Incident[]

POST /monitors/{monitor_id}/incidents/{incident_id}/acknowledge Acknowledge an open incident; mutes its alerts until it resolves

Parameters

  • monitor_id (path, required) — Monitor ID
  • incident_id (path, required) — Incident ID

Returns 200 · Incident

POST /monitors/{monitor_id}/incidents/{incident_id}/notes Add a private team note (never sent in alerts)

Parameters

  • monitor_id (path, required) — Monitor ID
  • incident_id (path, required) — Incident ID

Body (JSON)

body* string max length 5000

Returns 201 · IncidentNote

GET /organizations/{organization_id}/incidents Incidents across the monitors you can see, open first

Parameters

  • organization_id (path, required) — Organization ID
  • status (query) — one of open, resolved
  • monitor_id (query)
  • page (query)

Returns 200 · Incident[]

Checks and alerts

POST /monitors/{monitor_id}/check Queue a check now (uptime unless type says otherwise); a disabled type is 422

Parameters

  • monitor_id (path, required) — Monitor ID

Body (JSON)

type string one of uptime, ssl, dns-blocklist, sitemap, crawl, robots, lighthouse, domain, dns-record, reverse-monitor; default uptime

Returns 202 · object

POST /monitors/{monitor_id}/snooze Snooze alerts

Parameters

  • monitor_id (path, required) — Monitor ID

Body (JSON)

hours* integer one of 1, 4, 24, 168

Returns 200 · object

DELETE /monitors/{monitor_id}/snooze Resume alerts

Parameters

  • monitor_id (path, required) — Monitor ID

Returns 200 · object

Monitors

GET /monitors List monitors

Parameters

  • organization_id (query)
  • team_id (query)
  • page (query)

Returns 200 · Monitor[]

POST /monitors Create a website monitor; any check type can be turned on and set up here

Body (JSON)

url* string max length 2048
label string | null
tags string[] max items 20
team_id string | null
critical boolean Down alerts skip quiet hours
ssl_monitoring_enabled boolean SSL
ssl_interval_minutes integer | null SSL; min 15; max 1440
ssl_expiring_soon_days integer | null SSL; min 1; max 90
ssl_alert_on_every_change boolean SSL
uptime_monitoring_enabled boolean Uptime
uptime_interval_minutes integer | null Uptime; min 1; max 60
uptime_check_method string | null Uptime; one of GET, POST, PUT, PATCH
uptime_check_body string | null Uptime; max length 10000
uptime_check_headers object | array | string | null Request headers, e.g. {"Accept": "text/html"}. Objects are stored as sent; a string must be JSON.
uptime_check_string string | null Uptime; max length 500
uptime_check_absent_string string | null Uptime; max length 500
uptime_check_json_assertions object | array | string | null JSON response assertions (dot paths), e.g. [{"path": "status", "expected": "ok"}]. Objects are stored as sent; a string must be JSON.
uptime_check_header_patterns object | array | string | null Response headers that must match, a regex or substring, e.g. [{"header": "Content-Type", "pattern": "text/html"}]. Objects are stored as sent; a string must be JSON.
uptime_expected_codes string | null Uptime; max length 100
uptime_response_time_threshold_ms integer | null Uptime; min 0
uptime_response_time_variance_pct integer | null Uptime; min 1; max 1000
uptime_alert_after_failures integer | null Uptime; min 1; max 10
uptime_alert_after_minutes integer | null Uptime; min 1; max 60
uptime_timeout_seconds integer | null Uptime; min 1; max 30
uptime_max_redirects integer | null Uptime; min 0; max 10
heartbeat_enabled boolean Heartbeat
heartbeat_interval_minutes integer | null Heartbeat; min 1; max 1440
heartbeat_grace_minutes integer | null Heartbeat; min 0; max 60
heartbeat_cron_expression string | null Heartbeat; max length 120
heartbeat_timezone string | null Heartbeat: IANA timezone
dns_blocklist_monitoring_enabled boolean DNS blocklist
sitemap_monitoring_enabled boolean Sitemap
crawl_monitoring_enabled boolean Crawl
crawl_max_depth integer | null Crawl; min 1; max 20
crawl_max_pages integer | null Crawl; min 10; max 50000
crawl_time_limit_minutes integer | null Crawl: stop after this many minutes; min 5; max 240
crawl_interval_minutes integer | null Crawl; min 60; max 525600
crawl_alert_on_broken boolean Crawl
crawl_alert_on_mixed_content boolean Crawl
crawl_alert_on_console_errors boolean Crawl
crawl_alert_on_lighthouse_regression boolean Crawl
crawl_alert_on_screenshot_diff boolean Crawl
crawl_lighthouse_regression_threshold integer | null Crawl; min 0; max 100
crawl_screenshot_diff_threshold_pct integer | null Crawl; min 1; max 100
crawl_seed_from_sitemap boolean Crawl
crawl_respect_robots_txt boolean Crawl
crawl_check_external_links boolean Crawl
crawl_ignore_patterns string[] | string | null Crawl: URL patterns to skip, e.g. ["/admin/*"] (or one per line), up to 100
crawl_request_headers object | array | string | null Headers the crawler sends, e.g. {"Authorization": "Bearer …"}. Objects are stored as sent; a string must be JSON.
robots_txt_monitoring_enabled boolean Robots.txt
lighthouse_monitoring_enabled boolean Lighthouse
lighthouse_strategy string Lighthouse; one of mobile, desktop
lighthouse_thresholds object Lighthouse thresholds; keys you leave out keep their values; keys: min_score, max_fcp_ms, max_lcp_ms, max_tbt_ms, max_cls
domain_monitoring_enabled boolean Domain
dns_record_monitoring_enabled boolean DNS records
reverse_monitoring_enabled boolean Reverse monitor
reverse_monitor_host string | null Reverse monitor; max length 255
reverse_monitor_port integer | null Reverse monitor; min 1; max 65535
status_page_enabled boolean Status page
status_slug string | null Status page; max length 64
status_page_title string | null Status page; max length 255
status_page_message string | null Status page; max length 500
status_page_show string[] | null Status page; each one of uptime, ssl, heartbeat, incidents
organization_id string | null

Example

curl -X POST https://observe.live/api/v1/monitors \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","label":"Marketing site","tags":["marketing"],"uptime_interval_minutes":1,"crawl_monitoring_enabled":true,"lighthouse_monitoring_enabled":true,"domain_monitoring_enabled":true}'

Returns 201 · Monitor

GET /monitors/{monitor_id} Get a monitor

Parameters

  • monitor_id (path, required) — Monitor ID

Returns 200 · Monitor

PATCH /monitors/{monitor_id} Update a monitor: only the fields you send change; turning a check type on queues its first check

Parameters

  • monitor_id (path, required) — Monitor ID

Body (JSON)

url string max length 2048
label string | null
tags string[] max items 20
team_id string | null
critical boolean Down alerts skip quiet hours
ssl_monitoring_enabled boolean SSL
ssl_interval_minutes integer | null SSL; min 15; max 1440
ssl_expiring_soon_days integer | null SSL; min 1; max 90
ssl_alert_on_every_change boolean SSL
uptime_monitoring_enabled boolean Uptime
uptime_interval_minutes integer | null Uptime; min 1; max 60
uptime_check_method string | null Uptime; one of GET, POST, PUT, PATCH
uptime_check_body string | null Uptime; max length 10000
uptime_check_headers object | array | string | null Request headers, e.g. {"Accept": "text/html"}. Objects are stored as sent; a string must be JSON.
uptime_check_string string | null Uptime; max length 500
uptime_check_absent_string string | null Uptime; max length 500
uptime_check_json_assertions object | array | string | null JSON response assertions (dot paths), e.g. [{"path": "status", "expected": "ok"}]. Objects are stored as sent; a string must be JSON.
uptime_check_header_patterns object | array | string | null Response headers that must match, a regex or substring, e.g. [{"header": "Content-Type", "pattern": "text/html"}]. Objects are stored as sent; a string must be JSON.
uptime_expected_codes string | null Uptime; max length 100
uptime_response_time_threshold_ms integer | null Uptime; min 0
uptime_response_time_variance_pct integer | null Uptime; min 1; max 1000
uptime_alert_after_failures integer | null Uptime; min 1; max 10
uptime_alert_after_minutes integer | null Uptime; min 1; max 60
uptime_timeout_seconds integer | null Uptime; min 1; max 30
uptime_max_redirects integer | null Uptime; min 0; max 10
heartbeat_enabled boolean Heartbeat
heartbeat_interval_minutes integer | null Heartbeat; min 1; max 1440
heartbeat_grace_minutes integer | null Heartbeat; min 0; max 60
heartbeat_cron_expression string | null Heartbeat; max length 120
heartbeat_timezone string | null Heartbeat: IANA timezone
dns_blocklist_monitoring_enabled boolean DNS blocklist
sitemap_monitoring_enabled boolean Sitemap
crawl_monitoring_enabled boolean Crawl
crawl_max_depth integer | null Crawl; min 1; max 20
crawl_max_pages integer | null Crawl; min 10; max 50000
crawl_time_limit_minutes integer | null Crawl: stop after this many minutes; min 5; max 240
crawl_interval_minutes integer | null Crawl; min 60; max 525600
crawl_alert_on_broken boolean Crawl
crawl_alert_on_mixed_content boolean Crawl
crawl_alert_on_console_errors boolean Crawl
crawl_alert_on_lighthouse_regression boolean Crawl
crawl_alert_on_screenshot_diff boolean Crawl
crawl_lighthouse_regression_threshold integer | null Crawl; min 0; max 100
crawl_screenshot_diff_threshold_pct integer | null Crawl; min 1; max 100
crawl_seed_from_sitemap boolean Crawl
crawl_respect_robots_txt boolean Crawl
crawl_check_external_links boolean Crawl
crawl_ignore_patterns string[] | string | null Crawl: URL patterns to skip, e.g. ["/admin/*"] (or one per line), up to 100
crawl_request_headers object | array | string | null Headers the crawler sends, e.g. {"Authorization": "Bearer …"}. Objects are stored as sent; a string must be JSON.
robots_txt_monitoring_enabled boolean Robots.txt
lighthouse_monitoring_enabled boolean Lighthouse
lighthouse_strategy string Lighthouse; one of mobile, desktop
lighthouse_thresholds object Lighthouse thresholds; keys you leave out keep their values; keys: min_score, max_fcp_ms, max_lcp_ms, max_tbt_ms, max_cls
domain_monitoring_enabled boolean Domain
dns_record_monitoring_enabled boolean DNS records
reverse_monitoring_enabled boolean Reverse monitor
reverse_monitor_host string | null Reverse monitor; max length 255
reverse_monitor_port integer | null Reverse monitor; min 1; max 65535
status_page_enabled boolean Status page
status_slug string | null Status page; max length 64
status_page_title string | null Status page; max length 255
status_page_message string | null Status page; max length 500
status_page_show string[] | null Status page; each one of uptime, ssl, heartbeat, incidents

Example

curl -X PATCH https://observe.live/api/v1/monitors/{monitor_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"crawl_monitoring_enabled":true,"crawl_max_pages":500,"crawl_ignore_patterns":["/admin/*"],"lighthouse_strategy":"desktop","lighthouse_thresholds":{"min_score":80}}'

Returns 200 · Monitor

DELETE /monitors/{monitor_id} Delete a monitor

Parameters

  • monitor_id (path, required) — Monitor ID

Returns 204

GET /monitors/{monitor_id}/status Current up/down, incident, maintenance and snooze state

Parameters

  • monitor_id (path, required) — Monitor ID

Returns 200 · MonitorStatus

Results

GET /monitors/{monitor_id}/uptime Latest 50 uptime checks with 30-day uptime and 7-day average response time

Parameters

  • monitor_id (path, required) — Monitor ID

Returns 200 · UptimeCheck[]

GET /monitors/{monitor_id}/{type} Results for one check type, newest first

Parameters

  • monitor_id (path, required) — Monitor ID
  • type (path, required) — one of ssl, domain, dns, lighthouse, crawls, heartbeats, sitemap, robots, blocklist, reverse
  • per_page (query) — min 1; max 100; default 25
  • page (query)

Returns 200 · object[]

GET /monitors/{monitor_id}/sla Uptime (SLA) report for a range

Parameters

  • monitor_id (path, required) — Monitor ID
  • range (query) — one of 24h, 7d, 30d, custom; default 7d
  • start (query) — custom range, Y-m-d
  • end (query) — custom range, Y-m-d

Returns 200 · SlaReport

GET /monitors/{monitor_id}/crawls/{run_id}/pages Pages a crawl visited; filter=broken for broken links

Parameters

  • monitor_id (path, required) — Monitor ID
  • run_id (path, required) — Crawl ID (from /monitors/{monitor_id}/crawls)
  • filter (query) — one of success, failed, broken, mixed
  • search (query) — Part of a URL or title
  • per_page (query) — min 1; max 100; default 25
  • page (query)

Returns 200 · CrawledPage[]

Maintenance

GET /organizations/{organization_id}/maintenance-windows Maintenance windows

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · MaintenanceWindow[]

POST /organizations/{organization_id}/maintenance-windows Schedule a maintenance window (admins)

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

title* string max length 255
description string | null
starts_at* string
ends_at* string
monitor_ids string[] Specific monitors; omit monitor_ids, team_id and tags for every monitor
team_id string | null
tags string[] Monitors with any of these tags
recurrence string | null one of weekly, monthly, null
timezone string | null Keeps a repeating window's local time across DST

Returns 201 · MaintenanceWindow

DELETE /organizations/{organization_id}/maintenance-windows/{window_id} Cancel a maintenance window (admins)

Parameters

  • organization_id (path, required) — Organization ID
  • window_id (path, required) — Maintenance window ID

Returns 200 · MaintenanceWindow

Status pages

GET /organizations/{organization_id}/status-pages Additional status pages

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · StatusPage[]

POST /organizations/{organization_id}/status-pages Create a status page (admins)

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

title* string max length 255
slug* string Lowercase letters, digits and dashes; slugified for you; max length 64
message string | null
site_ids* string[] Monitors on the page
logo_url string | null
accent_color string | null Hex colour, e.g. #0f766e
locale string one of en, es, fr, de, nl, pt; default en
private boolean Only people with the private link can see it
auto_updates boolean Post an update automatically when a monitor on the page goes down and comes back

Example

curl -X POST https://observe.live/api/v1/organizations/{organization_id}/status-pages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Acme status","slug":"acme","site_ids":["MONITOR_ID"]}'

Returns 201 · StatusPage

PATCH /organizations/{organization_id}/status-pages/{status_page_id} Edit a status page (admins); fields you leave out keep their values

Parameters

  • organization_id (path, required) — Organization ID
  • status_page_id (path, required) — Status page ID

Body (JSON)

title string max length 255
slug string Lowercase letters, digits and dashes; slugified for you; max length 64
message string | null
site_ids string[] Monitors on the page
logo_url string | null
accent_color string | null Hex colour, e.g. #0f766e
locale string one of en, es, fr, de, nl, pt; default en
private boolean Only people with the private link can see it
auto_updates boolean Post an update automatically when a monitor on the page goes down and comes back

Returns 200 · StatusPage

DELETE /organizations/{organization_id}/status-pages/{status_page_id} Delete a status page (admins)

Parameters

  • organization_id (path, required) — Organization ID
  • status_page_id (path, required) — Status page ID

Returns 204

GET /organizations/{organization_id}/status-page-updates Updates posted to your status pages, pinned first

Parameters

  • organization_id (path, required) — Organization ID
  • page (query)

Returns 200 · StatusPageUpdate[]

POST /organizations/{organization_id}/status-page-updates Post an update (admins); it is public at once

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

title* string max length 255
body* string max length 5000
severity* string one of info, warning, high, resolved, scheduled
pinned boolean
status_page_id string | null An additional page; omit for the main page

Example

curl -X POST https://observe.live/api/v1/organizations/{organization_id}/status-page-updates \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Database maintenance","body":"Checkout will be read-only from 22:00 to 22:30 UTC.","severity":"scheduled","pinned":true}'

Returns 201 · StatusPageUpdate

PATCH /organizations/{organization_id}/status-page-updates/{update_id} Edit or pin an update (admins)

Parameters

  • organization_id (path, required) — Organization ID
  • update_id (path, required) — Status page update ID

Body (JSON)

title string max length 255
body string max length 5000
severity string one of info, warning, high, resolved, scheduled
pinned boolean

Returns 200 · StatusPageUpdate

DELETE /organizations/{organization_id}/status-page-updates/{update_id} Delete an update (admins)

Parameters

  • organization_id (path, required) — Organization ID
  • update_id (path, required) — Status page update ID

Returns 204

Notifications

GET /organizations/{organization_id}/notification-channels Where alerts go (admins). Secrets are never returned

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · NotificationChannel[]

POST /organizations/{organization_id}/notification-channels Add a destination (admins)

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

type* string one of email, slack, webhook, discord, telegram, pagerduty, opsgenie, jsm, teams, googlechat, pushover, ntfy
label string | null
team_id string | null Only alerts for this team's monitors
enabled boolean
use_org_recipients boolean email: send to the organization's owners and admins (default)
email string email: a fixed address when use_org_recipients is false
webhook_url string slack, discord, teams, googlechat and webhook
bot_token string telegram
chat_id string telegram
routing_key string pagerduty
api_key string opsgenie and jsm (Jira Service Management Operations, Opsgenie's successor): the API integration key
eu_region boolean opsgenie: api.eu.opsgenie.com
priority string opsgenie and jsm: auto (P1 for critical monitors, else P3) or a fixed priority; one of auto, P1, P2, P3, P4, P5
responder_team string opsgenie and jsm: team that receives the alert (default: the integration's team); max length 100
api_token string pushover
user_key string pushover
topic string ntfy
server_url string ntfy: your own server (default ntfy.sh)
event_types string[] Only these events; omit (or all_events: true) for every event; each one of uptime_incident_opened, uptime_incident_resolved, performance_budget_exceeded, performance_budget_recovered, ssl_expiring_soon, ssl_certificate_invalid, certificate_changed, sitemap_check_failed, lighthouse_scores_regressed, domain_expiring_soon, domain_expired, domain_blocklist_listed, server_health_check_failed, server_ssl_check_failed, server_ping_failed, server_heartbeat_missed, server_recovered, port_scan_anomaly, health_check_missed, health_check_failed, health_check_recovered, ai_check_failed, dns_record_changed, dns_nameservers_out_of_sync, reverse_monitor_exposed, crawl_new_issues_found, monthly_report
all_events boolean
delivery_hours string one of always, business, outside
tag_filter string[] | string | null Only monitors with any of these tags
category_modes object Per event category: immediate, digest or off
quiet_hours_start string | null H:i
quiet_hours_end string | null H:i

Example

curl -X POST https://observe.live/api/v1/organizations/{organization_id}/notification-channels \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"webhook","label":"Incident bot","webhook_url":"https://hooks.example.com/observe","event_types":["uptime_incident_opened","uptime_incident_resolved"]}'

Returns 201 · NotificationChannel

PATCH /organizations/{organization_id}/notification-channels/{channel_id} Edit a destination (admins); fields you leave out keep their values

Parameters

  • organization_id (path, required) — Organization ID
  • channel_id (path, required) — Notification channel ID

Body (JSON)

type string one of email, slack, webhook, discord, telegram, pagerduty, opsgenie, jsm, teams, googlechat, pushover, ntfy
label string | null
team_id string | null Only alerts for this team's monitors
enabled boolean
use_org_recipients boolean email: send to the organization's owners and admins (default)
email string email: a fixed address when use_org_recipients is false
webhook_url string slack, discord, teams, googlechat and webhook
bot_token string telegram
chat_id string telegram
routing_key string pagerduty
api_key string opsgenie and jsm (Jira Service Management Operations, Opsgenie's successor): the API integration key
eu_region boolean opsgenie: api.eu.opsgenie.com
priority string opsgenie and jsm: auto (P1 for critical monitors, else P3) or a fixed priority; one of auto, P1, P2, P3, P4, P5
responder_team string opsgenie and jsm: team that receives the alert (default: the integration's team); max length 100
api_token string pushover
user_key string pushover
topic string ntfy
server_url string ntfy: your own server (default ntfy.sh)
event_types string[] Only these events; omit (or all_events: true) for every event; each one of uptime_incident_opened, uptime_incident_resolved, performance_budget_exceeded, performance_budget_recovered, ssl_expiring_soon, ssl_certificate_invalid, certificate_changed, sitemap_check_failed, lighthouse_scores_regressed, domain_expiring_soon, domain_expired, domain_blocklist_listed, server_health_check_failed, server_ssl_check_failed, server_ping_failed, server_heartbeat_missed, server_recovered, port_scan_anomaly, health_check_missed, health_check_failed, health_check_recovered, ai_check_failed, dns_record_changed, dns_nameservers_out_of_sync, reverse_monitor_exposed, crawl_new_issues_found, monthly_report
all_events boolean
delivery_hours string one of always, business, outside
tag_filter string[] | string | null Only monitors with any of these tags
category_modes object Per event category: immediate, digest or off
quiet_hours_start string | null H:i
quiet_hours_end string | null H:i

Returns 200 · NotificationChannel

DELETE /organizations/{organization_id}/notification-channels/{channel_id} Remove a destination (admins)

Parameters

  • organization_id (path, required) — Organization ID
  • channel_id (path, required) — Notification channel ID

Returns 204

POST /organizations/{organization_id}/notification-channels/{channel_id}/test Send a sample alert through the destination (admins, 5 a minute)

Parameters

  • organization_id (path, required) — Organization ID
  • channel_id (path, required) — Notification channel ID

Returns 200 · object

Members and teams

GET /organizations/{organization_id}/members Members and their roles (admins)

Parameters

  • organization_id (path, required) — Organization ID
  • page (query)

Returns 200 · Member[]

POST /organizations/{organization_id}/members Add someone with an account, or email an invitation (admins)

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

email* string
role string one of viewer, member, admin; default member
team_id string | null

Example

curl -X POST https://observe.live/api/v1/organizations/{organization_id}/members \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","role":"member"}'

Returns 201 · object

DELETE /organizations/{organization_id}/members/{user_id} Remove a member (admins; not the owner or the billing owner)

Parameters

  • organization_id (path, required) — Organization ID
  • user_id (path, required) — User ID

Returns 204

GET /organizations/{organization_id}/invitations Pending invitations (admins)

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · Invitation[]

DELETE /organizations/{organization_id}/invitations/{invitation_id} Revoke an invitation (admins)

Parameters

  • organization_id (path, required) — Organization ID
  • invitation_id (path, required) — Invitation ID

Returns 204

GET /organizations/{organization_id}/teams Teams and their members

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · Team[]

POST /organizations/{organization_id}/teams Create a team (admins); you become its owner

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

name* string max length 255

Returns 201 · Team

PATCH /organizations/{organization_id}/teams/{team_id} Rename a team (admins and the team owner)

Parameters

  • organization_id (path, required) — Organization ID
  • team_id (path, required) — Team ID

Body (JSON)

name* string max length 255

Returns 200 · Team

DELETE /organizations/{organization_id}/teams/{team_id} Delete a team (admins); its monitors stay, without a team

Parameters

  • organization_id (path, required) — Organization ID
  • team_id (path, required) — Team ID

Returns 204

POST /organizations/{organization_id}/teams/{team_id}/members Add an organization member to a team

Parameters

  • organization_id (path, required) — Organization ID
  • team_id (path, required) — Team ID

Body (JSON)

user_id* string
role string one of member, admin, owner; default member

Returns 201 · Team

DELETE /organizations/{organization_id}/teams/{team_id}/members/{user_id} Remove someone from a team (not its owner)

Parameters

  • organization_id (path, required) — Organization ID
  • team_id (path, required) — Team ID
  • user_id (path, required) — User ID

Returns 204

Reports

GET /organizations/{organization_id}/reports Saved reports

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · Report[]

POST /organizations/{organization_id}/reports Save a report (members and admins)

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

name* string max length 120
scope string Which monitors; default all; one of all, monitors, groups, tags, teams
scope_ids string[] Monitor, group or team IDs, or tags (wildcards allowed), for the scope
range string Default 30d; one of 7d, 30d, 90d, last_month, last_quarter, custom
custom_start string | null
custom_end string | null
compare boolean Also compute the previous window of the same length; default true
group_by string one of site, group, tag, team
filter_tags string[] Only monitors with one of these tags (wildcards allowed), whatever the breakdown
filter_team_ids string[] Only monitors in these teams, whatever the breakdown
sections string[] Default uptime, response, incidents; each one of uptime, response, incidents, expiry, lighthouse, crawl, heartbeats, dns

Returns 201 · Report

POST /organizations/{organization_id}/reports/run Run a report config without saving it

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

scope string Which monitors; default all; one of all, monitors, groups, tags, teams
scope_ids string[] Monitor, group or team IDs, or tags (wildcards allowed), for the scope
range string Default 30d; one of 7d, 30d, 90d, last_month, last_quarter, custom
custom_start string | null
custom_end string | null
compare boolean Also compute the previous window of the same length; default true
group_by string one of site, group, tag, team
filter_tags string[] Only monitors with one of these tags (wildcards allowed), whatever the breakdown
filter_team_ids string[] Only monitors in these teams, whatever the breakdown
sections string[] Default uptime, response, incidents; each one of uptime, response, incidents, expiry, lighthouse, crawl, heartbeats, dns

Returns 200 · ReportResult

GET /organizations/{organization_id}/reports/{report_id} Get a saved report's config

Parameters

  • organization_id (path, required) — Organization ID
  • report_id (path, required) — Report ID

Returns 200 · Report

GET /organizations/{organization_id}/reports/{report_id}/run Run a saved report now (non-admins see their teams' monitors)

Parameters

  • organization_id (path, required) — Organization ID
  • report_id (path, required) — Report ID

Returns 200 · ReportResult

GET /organizations/{organization_id}/groups Monitor groups

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · MonitorGroup[]

POST /organizations/{organization_id}/groups Create a monitor group (members and admins)

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

name* string max length 100
monitor_ids string[]

Returns 201 · MonitorGroup

PATCH /organizations/{organization_id}/groups/{group_id} Rename a group or replace its monitors

Parameters

  • organization_id (path, required) — Organization ID
  • group_id (path, required) — Monitor group ID

Body (JSON)

name string max length 100
monitor_ids string[]

Returns 200 · MonitorGroup

DELETE /organizations/{organization_id}/groups/{group_id} Delete a group (its monitors are kept)

Parameters

  • organization_id (path, required) — Organization ID
  • group_id (path, required) — Monitor group ID

Returns 204

Servers

GET /organizations/{organization_id}/servers Server monitors you can see, with their checks' state

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · Server[]

POST /organizations/{organization_id}/servers Add a server monitor (members, not viewers); the checks it turns on run once now

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

name* string max length 255
host* string max length 255
team_id string | null A team in this organization
tags string[] | string | null
ports_expected_open integer[] | string | null Ports that must accept connections, e.g. [22, 443]
ports_expected_closed integer[] | string | null Ports that must refuse connections
heartbeat_enabled boolean
full_port_scan_enabled boolean
heartbeat_interval_minutes integer | null min 1; max 10080
heartbeat_grace_minutes integer | null min 0; max 1440
ping_enabled boolean
ping_packet_count integer | null min 1; max 100
ping_packet_size integer | null min 1; max 65500
ping_max_hops integer | null min 1; max 255
ping_acceptable_loss_pct integer | null min 0; max 100
ssl_check_enabled boolean
ssl_check_port integer | null min 1; max 65535
health_check_enabled boolean
health_check_url string | null max length 2048
health_check_expected_code integer | null min 100; max 599
health_check_expected_string string | null max length 255
port_send_strings object | string | null Text to send per port, e.g. {"6379": "PING"}
port_expected_responses object | string | null Text each port must answer with, e.g. {"6379": "PONG"}

Example

curl -X POST https://observe.live/api/v1/organizations/{organization_id}/servers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-1","host":"web-1.example.com","ports_expected_open":[22,443],"ping_enabled":true,"heartbeat_enabled":true}'

Returns 201 · Server

PATCH /organizations/{organization_id}/servers/{server_id} Edit a server monitor; fields you leave out keep their values

Parameters

  • organization_id (path, required) — Organization ID
  • server_id (path, required) — Server ID

Body (JSON)

name string max length 255
host string max length 255
team_id string | null A team in this organization
tags string[] | string | null
ports_expected_open integer[] | string | null Ports that must accept connections, e.g. [22, 443]
ports_expected_closed integer[] | string | null Ports that must refuse connections
heartbeat_enabled boolean
full_port_scan_enabled boolean
heartbeat_interval_minutes integer | null min 1; max 10080
heartbeat_grace_minutes integer | null min 0; max 1440
ping_enabled boolean
ping_packet_count integer | null min 1; max 100
ping_packet_size integer | null min 1; max 65500
ping_max_hops integer | null min 1; max 255
ping_acceptable_loss_pct integer | null min 0; max 100
ssl_check_enabled boolean
ssl_check_port integer | null min 1; max 65535
health_check_enabled boolean
health_check_url string | null max length 2048
health_check_expected_code integer | null min 100; max 599
health_check_expected_string string | null max length 255
port_send_strings object | string | null Text to send per port, e.g. {"6379": "PING"}
port_expected_responses object | string | null Text each port must answer with, e.g. {"6379": "PONG"}

Returns 200 · Server

DELETE /organizations/{organization_id}/servers/{server_id} Delete a server monitor and its history

Parameters

  • organization_id (path, required) — Organization ID
  • server_id (path, required) — Server ID

Returns 204

Organizations

GET /organizations Organizations you belong to, with your role, plan, usage and billing state

Returns 200 · Organization[]

GET /organizations/{organization_id}/settings General, monthly report, business hours, main status page and health-check settings (admins)

Parameters

  • organization_id (path, required) — Organization ID

Returns 200 · OrganizationSettings

PATCH /organizations/{organization_id}/settings Change settings (admins); fields you leave out keep their values

Parameters

  • organization_id (path, required) — Organization ID

Body (JSON)

name string max length 255
monthly_report_enabled boolean
status_page_enabled boolean
status_slug string | null max length 64
status_page_custom_domain string | null When custom domains are on: verify it on the Org settings page
status_page_title string | null max length 255
status_page_message string | null max length 500
status_page_logo_url string | null max length 2048
status_page_favicon_url string | null max length 2048
status_page_accent_color string | null max length 32
status_page_site_ids string[] | null Monitors on the main status page; empty for all of them
health_check_slug string | null max length 64
health_check_interval_minutes integer | null min 1; max 10080
health_check_grace_minutes integer | null min 0; max 1440
monthly_report_recipients string[] | string | null Extra monthly report recipients (up to 10), as a list or one comma-separated string
status_page_private boolean Only people with the private link can see the page
status_page_auto_updates boolean
status_page_locale string
health_check_url string | null max length 2048
health_check_secret string | null Write-only; sent as a bearer token to health_check_url
timezone string IANA timezone
business_hours_start string
business_hours_end string
business_days integer[] min 1

Example

curl -X PATCH https://observe.live/api/v1/organizations/{organization_id}/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status_page_enabled":true,"status_slug":"acme","status_page_title":"Acme status","business_days":[1,2,3,4,5]}'

Returns 200 · OrganizationSettings

Objects

Monitor
  • id string
  • url string
  • label string | null
  • tags string[]
  • critical boolean
  • organization_id string
  • team_id string | null
  • uptime object — keys: enabled, interval_minutes, check_method, expected_codes, alert_after_failures, alert_after_minutes, check_body, check_headers, check_string, check_absent_string, json_assertions, header_patterns, response_time_threshold_ms, response_time_variance_pct, timeout_seconds, max_redirects
  • ssl object — keys: enabled, interval_minutes, expiring_soon_days, alert_on_every_change
  • heartbeat object — keys: enabled, interval_minutes, grace_minutes, cron_expression, timezone, ping_url
  • crawl object — keys: enabled, max_depth, max_pages, time_limit_minutes, interval_minutes, alert_on_broken, alert_on_mixed_content, alert_on_console_errors, alert_on_lighthouse_regression, alert_on_screenshot_diff, lighthouse_regression_threshold, screenshot_diff_threshold_pct, seed_from_sitemap, respect_robots_txt, check_external_links, ignore_patterns, request_headers
  • lighthouse object — keys: enabled, strategy, thresholds
  • sitemap object — keys: enabled
  • robots object — keys: enabled
  • domain object — keys: enabled
  • dns_blocklist object — keys: enabled
  • dns_records object — keys: enabled
  • reverse_monitor object — keys: enabled, host, port
  • status_page object — keys: enabled, slug, title, message, show, url
  • alerts_snoozed_until string | null
  • created_at string | null
  • updated_at string | null
MonitorStatus
  • monitor_id string
  • url string
  • up boolean | null
  • has_open_incident boolean
  • under_maintenance boolean
  • last_checked_at string | null
  • ssl object — keys: enabled, last_checked_at
  • heartbeat object — keys: enabled, ok
  • alerts_snoozed_until string | null
UptimeCheck
  • id string
  • up boolean
  • response_code integer | null
  • response_time_ms integer | null
  • failure_reason string | null
  • error_message string | null
  • checked_at string
Incident
  • id string
  • monitor_id string
  • started_at string
  • ended_at string | null
  • resolved boolean
  • duration_seconds integer | null
  • source string | null
  • reason string | null
  • acknowledged_at string | null
  • notes IncidentNote[]
IncidentNote
  • id string
  • body string
  • author string | null
  • created_at string | null
Organization
  • id string
  • name string
  • slug string
  • role string | null
  • plan string
  • monitor_limit integer
  • monitor_count integer
  • one_minute_monitor_limit integer
  • one_minute_monitor_count integer
  • on_trial boolean
  • subscribed boolean
  • payment_past_due boolean
MaintenanceWindow
  • id string
  • title string
  • description string | null
  • starts_at string
  • ends_at string
  • status string — one of scheduled, active, completed, cancelled
  • monitor_ids string[] | null
  • team_id string | null
  • tags string[] | null
  • recurrence string | null — one of weekly, monthly, null
  • timezone string | null
CronCheck
  • id integer
  • uuid string
  • name string
  • type string
  • cron_expression string
  • grace_time_in_minutes integer
  • server_timezone string | null
  • description string
  • ping_url string
OhDearCheck
  • id string
  • type string — one of uptime, certificate_health
  • label string
  • enabled boolean
  • latest_run_ended_at string | null
  • latest_run_result string — one of pending, succeeded, failed
  • summary string
  • settings object
  • active_snooze object | null
OhDearMonitor
  • id string
  • team_id string
  • type string
  • url string
  • uses_https boolean
  • sort_url string
  • label string
  • group_name string
  • tags string[]
  • description string | null
  • notes string | null
  • latest_run_date string | null
  • summarized_check_result string — one of pending, succeeded, failed
  • checks OhDearCheck[]
  • created_at string | null
  • updated_at string | null
Report
  • id string
  • name string
  • scope string — Which monitors; default all; one of all, monitors, groups, tags, teams
  • scope_ids string[] — Monitor, group or team IDs, or tags (wildcards allowed), for the scope
  • range string — Default 30d; one of 7d, 30d, 90d, last_month, last_quarter, custom
  • custom_start string | null
  • custom_end string | null
  • compare boolean — Also compute the previous window of the same length; default true
  • group_by string — one of site, group, tag, team
  • filter_tags string[] — Only monitors with one of these tags (wildcards allowed), whatever the breakdown
  • filter_team_ids string[] — Only monitors in these teams, whatever the breakdown
  • sections string[] — Default uptime, response, incidents; each one of uptime, response, incidents, expiry, lighthouse, crawl, heartbeats, dns
  • schedule string | null — one of weekly, monthly, null
  • created_at string | null
  • updated_at string | null
ReportMetrics
  • checks integer
  • up integer
  • uptime number | null
  • timed integer
  • avg_ms integer | null
  • p50_ms integer | null — Daily medians averaged, weighted by timed checks
  • p95_ms integer | null — Daily p95s averaged, weighted by timed checks
  • downtime_seconds integer
  • incident_count integer
  • mttr_seconds number | null
ReportResult
  • config object — keys: scope, scope_ids, range, custom_start, custom_end, compare, group_by, filter_tags, filter_team_ids, sections
  • start string
  • end string
  • previous_start string | null
  • previous_end string | null
  • summary object — keys: sites, metrics, previous, heartbeats_missed, expiring, broken_links, mixed_content, dns_changes
  • groups object[]
  • sites object[]
  • incidents object[]
  • daily object — Y-m-d => uptime %
MonitorGroup
  • id string
  • name string
  • monitor_ids string[]
ValidationError
  • message string
  • errors object
PageMeta
  • current_page integer
  • last_page integer
  • per_page integer
  • total integer
SlaReport
  • start string
  • end string
  • uptime number | null
  • total_checks integer
  • up_checks integer
  • down_checks integer
  • mttr_seconds number | null
  • downtime_seconds integer
  • incident_count integer
  • resolved_incident_count integer
  • ongoing_incident_count integer
  • percentiles object — keys: p50, p95, p99, max, sample
  • trend object — keys: uptime, downtime_seconds, mttr_seconds
  • periods object[]
CrawledPage
  • id string
  • url string
  • final_url string | null
  • found_on_url string | null
  • status_code integer | null
  • success boolean
  • broken boolean
  • title string | null
  • depth integer | null
  • transfer_time_ms integer | null
  • mixed_content object[]
StatusPage
  • id string
  • slug string
  • title string
  • message string | null
  • monitor_ids string[] | null
  • locale string
  • logo_url string | null
  • accent_color string | null
  • private boolean
  • auto_updates boolean
  • url string
StatusPageUpdate
  • id string
  • status_page_id string | null
  • title string
  • body string
  • severity string
  • pinned boolean
  • published_at string | null
NotificationChannel
  • id string
  • type string
  • label string | null
  • enabled boolean
  • team_id string | null
  • destination string | null — The address, topic or host alerts go to; secrets are never returned
  • event_types string[] | null — null means every event
  • delivery_hours string
  • tag_filter string[] | null
  • category_modes object | null
  • quiet_hours_start string | null
  • quiet_hours_end string | null
  • signing_secret string | null — webhook: the key for Observe-Signature (HMAC-SHA256 of the raw body)
Member
  • id string
  • name string | null
  • email string
  • role string | null
Invitation
  • id string
  • email string
  • role string
  • team_id string | null
  • expires_at string
Team
  • id string
  • name string
  • members Member[]
OrganizationSettings
  • name string — max length 255
  • monthly_report_enabled boolean
  • status_page_enabled boolean
  • status_slug string | null — max length 64
  • status_page_custom_domain string | null
  • status_page_title string | null — max length 255
  • status_page_message string | null — max length 500
  • status_page_logo_url string | null — max length 2048
  • status_page_favicon_url string | null — max length 2048
  • status_page_accent_color string | null — max length 32
  • status_page_site_ids string[] | null
  • health_check_slug string | null — max length 64
  • health_check_interval_minutes integer | null — min 1; max 10080
  • health_check_grace_minutes integer | null — min 0; max 1440
  • monthly_report_recipients string[]
  • status_page_private boolean
  • status_page_auto_updates boolean
  • status_page_locale string
  • health_check_url string | null — max length 2048
  • timezone string
  • business_hours_start string
  • business_hours_end string
  • business_days integer[] — min 1
  • status_page_custom_domain_verified boolean
  • health_check_secret_set boolean — The secret itself is never returned
Server
  • id string
  • name string
  • host string
  • team_id string | null
  • tags string[] | null
  • ports_expected_open integer[]
  • ports_expected_closed integer[]
  • full_port_scan_enabled boolean
  • port_send_strings object | null
  • port_expected_responses object | null
  • heartbeat_enabled boolean
  • heartbeat_interval_minutes integer | null
  • heartbeat_grace_minutes integer | null
  • heartbeat_url string | null — POST to it from the server while the heartbeat is on
  • heartbeat_ok boolean | null
  • last_heartbeat_at string | null
  • ping_enabled boolean
  • ping_packet_count integer | null
  • ping_packet_size integer | null
  • ping_max_hops integer | null
  • ping_acceptable_loss_pct integer | null
  • ssl_check_enabled boolean
  • ssl_check_port integer | null
  • health_check_enabled boolean
  • health_check_url string | null
  • health_check_expected_code integer | null
  • health_check_expected_string string | null
  • alerts_snoozed_until string | null