Developer platform

API reference

Everything you can do in the dashboard, from your code. Create monitors from your deploy pipeline, open maintenance windows, read incidents and uptime, and publish status-page updates. JSON in, JSON out, predictable errors.

Introduction

The base URL is https://monitermysite.com/api/v1. Every request and response is JSON. Dates are ISO 8601 in UTC. Every object carries an object field and lists wrap their items in data with has_more.

The API is available on every plan. Plan limits that apply in the dashboard (monitor count, fastest interval, regions per monitor, status pages, alert channels) apply here too and are reported as plan_limit_error. The current API version is reported in the X-Api-Version header; breaking changes will ship as a new version path.

Your first requestbash
curl https://monitermysite.com/api/v1/account \
  -H "Authorization: Bearer mms_live_…"

Authentication

Create keys under Developer in the dashboard (owners and admins). A key belongs to one workspace, has a read or read + write scope and an optional expiry. The secret, mms_live_ followed by 40 characters, is shown once; only its SHA-256 is stored.

Send it as a bearer token. Never put it in a URL. Revoke a key from the same page the moment it leaks; requests with it fail immediately with api_key_revoked. Repeated failed authentications from one address are limited to 30 per minute.

Headerhttp
Authorization: Bearer mms_live_8Fj2…Qx9A

Errors

Errors use conventional HTTP status codes and a consistent body with a type you can switch on, a more specific code, a human message and, for validation errors, the offending param.

typeStatusMeaning
authentication_error401No key, a malformed key, a revoked key or an expired key. code is api_key_missing, invalid_api_key, api_key_revoked or api_key_expired.
permission_error403The key is read-only and the endpoint writes (insufficient_scope).
plan_limit_error403A plan limit was reached (monitors, interval, regions, status pages, channels). upgrade_to names the plan that lifts it.
invalid_request_error400 / 415Validation failed; param names the field. code is parameter_missing, parameter_invalid, invalid_json or unsupported_media_type.
not_found_error404The object does not exist in this workspace.
idempotency_error400An Idempotency-Key was reused for a different request.
rate_limit_error429Too many requests this minute; Retry-After says how long to wait.
api_error500Something failed on our side. Quote X-Request-Id when you contact support.
Error responsejson
HTTP/1.1 400 Bad Request
X-Request-Id: req_4c1e…

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "`interval_sec`: Number must be greater than or equal to 10",
    "param": "interval_sec",
    "doc_url": "https://monitermysite.com/docs/api"
  }
}

Rate limits

Requests are counted per workspace in one-minute windows. The allowance depends on the plan; every response carries the limit, what is left and when the window resets. Over the limit you get 429 rate_limit_error with a Retry-After header. Back off and retry; do not poll faster than your monitors are checked.

PlanRequests / minuteActive API keys
Starter602
Launch3005
Growth60020
Summit1,20050
Headers on every responsehttp
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 1760000460
Retry-After: 23          # only on 429

Idempotency

Network errors happen mid-request. To retry a POST safely, send an Idempotency-Key header with any unique string (a UUID, a deploy id). For 24 hours the same key on the same endpoint returns the original response, marked with Idempotent-Replayed: true, instead of creating a second object. Reusing a key on a different endpoint is an idempotency_error.

Safe retrieshttp
Idempotency-Key: 6f1c2a0e-deploy-4.3.0

Audit trail

Every write through the API is recorded in the workspace audit log with the key's name, the client address and the fields that changed, exactly like changes made by a person in the dashboard. Give each integration its own key so the log tells them apart.

Audit entrytext
API key Deploy pipeline (mms_live_8Fj2…) created monitor Checkout API
2026-10-09 08:14 UTC · 203.0.113.9 · 4 fields changed

Account

Who am I: the workspace this key belongs to, its plan and limits.

Retrieve the account

GET/v1/account
read scope

Returns the workspace, the effective plan with its limits, current usage and the scopes of the key you are using. A good first call to test a key.

Requestbash
curl https://monitermysite.com/api/v1/account \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{
  "object": "account",
  "workspace": { "id": "cm2x…", "name": "Acme Inc", "slug": "acme-k3j9d2", "created_at": "2026-10-01T09:12:00.000Z" },
  "plan": { "id": "team", "name": "Growth", "limits": { "monitors": 200, "min_interval_sec": 30, "api_requests_per_minute": 600, "api_keys": 20, … } },
  "usage": { "monitors": 42, "status_pages": 2, "members": 5 },
  "api_key": { "id": "cm2y…", "name": "Deploy pipeline", "scopes": ["read", "write"], "created_at": "…", "expires_at": null },
  "rate_limit": { "requests_per_minute": 600 }
}

Monitors

Create and manage checks. Validation and plan limits are exactly those of the dashboard, so anything the form accepts, the API accepts.

List monitors

GET/v1/monitors
read scope

All monitors in the workspace, oldest first. Filter with `type`, `status` (up, down, paused, pending, maintenance), `tag` and `q` (matches name or target).

Query parameters
limitinteger
Objects per page, 1–100. Default 20.
starting_afterstring
Cursor: the id of the last object on the previous page.
ending_beforestring
Cursor: the id of the first object on the next page (paging backwards).
typeenum
Only monitors of this type.
statusenum
Only monitors with this status.
tagstring
Only monitors carrying this tag.
qstring
Case-insensitive search in name and target.
Requestbash
curl "https://monitermysite.com/api/v1/monitors?status=down&limit=50" \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{
  "object": "list",
  "data": [
    {
      "object": "monitor",
      "id": "cm2z…",
      "name": "Checkout API",
      "type": "http",
      "target": "https://api.acme.com/health",
      "status": "down",
      "active": true,
      "interval_sec": 30,
      "regions": ["nyc3", "fra1", "sgp1"],
      "confirm_regions": 2,
      "last_check": { "checked_at": "2026-10-09T08:14:02.000Z", "response_time_ms": 0, "error": "HTTP 503" },
      …
    }
  ],
  "has_more": false,
  "url": "/v1/monitors"
}

Create a monitor

POST/v1/monitors
write scope

Creates a monitor and runs the first check within seconds. Send an `Idempotency-Key` header to make retries safe. Returns 403 `plan_limit_error` with `upgrade_to` when the plan's monitor count, interval or region limit is reached.

Body parameters
namestringrequired
Display name, up to 100 characters.
typeenumrequired
http, keyword, ping, port, dns, ssl, heartbeat or domain. Cannot be changed later.
targetstringrequired
URL for http/keyword, host or IP for ping/port, hostname for dns/ssl, registered domain for domain. Not used for heartbeat.
interval_secinteger
Seconds between checks: 10–86400. The minimum depends on your plan. Default 300. Ignored for domain (daily) and heartbeat (expected ping interval).
timeout_secinteger
1–60, default 30.
regionsstring[]
Region codes, e.g. ["nyc3","fra1"]. Your plan sets how many. Default ["nyc3"].
confirm_regionsinteger
How many regions must agree before an incident opens. Default 1.
fail_thresholdinteger
Consecutive failures per region before that region counts as down, 1–10. Default 2.
tagsstring[]
Up to 10 tags.
contact_idsstring[]
Alert contacts to notify.
response_time_threshold_msinteger | null
Slow-response alert threshold for http/keyword monitors.
httpobject
method, headers (object), body, auth_type (none/basic/bearer), auth_user, auth_pass, follow_redirects, expected_status_codes (e.g. 200-299,301), check_ssl, ssl_expiry_days.
keywordobject
text (required for keyword monitors) and condition (contains or not_contains).
portinteger
Required for port monitors.
dnsobject
record_type (A, AAAA, CNAME, MX, NS, TXT) and optional expected value(s).
heartbeatobject
grace_sec: how late a ping may be before the monitor is down. Default 300.
domainobject
expiry_days: start warning this many days before the registration lapses. Default 30.
Requestbash
curl https://monitermysite.com/api/v1/monitors \
  -H "Authorization: Bearer $MMS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-2026-10-09-01" \
  -d '{
    "name": "Checkout API",
    "type": "http",
    "target": "https://api.acme.com/health",
    "interval_sec": 60,
    "regions": ["nyc3", "fra1"],
    "confirm_regions": 2,
    "http": { "expected_status_codes": "200", "check_ssl": true },
    "tags": ["prod", "checkout"]
  }'
Responsejson
HTTP/1.1 201 Created
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1760000400
X-Request-Id: req_7f3a…

{ "object": "monitor", "id": "cm30…", "name": "Checkout API", "type": "http", "status": "pending", … }

Retrieve a monitor

GET/v1/monitors/{id}
read scope

One monitor by id, including its last check and expiry information for SSL and domain monitors.

Requestbash
curl https://monitermysite.com/api/v1/monitors/cm30… \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "monitor", "id": "cm30…", "name": "Checkout API", "status": "up", "ssl": { "expires_at": "2027-01-04T00:00:00.000Z", "expiry_days": 14 }, … }

Update a monitor

PATCH/v1/monitors/{id}
write scope

Partial update: only the fields you send change. `type` cannot be changed. The next check runs immediately after the update.

Body parameters
namestringrequired
Display name, up to 100 characters.
targetstringrequired
URL for http/keyword, host or IP for ping/port, hostname for dns/ssl, registered domain for domain. Not used for heartbeat.
interval_secinteger
Seconds between checks: 10–86400. The minimum depends on your plan. Default 300. Ignored for domain (daily) and heartbeat (expected ping interval).
timeout_secinteger
1–60, default 30.
regionsstring[]
Region codes, e.g. ["nyc3","fra1"]. Your plan sets how many. Default ["nyc3"].
confirm_regionsinteger
How many regions must agree before an incident opens. Default 1.
fail_thresholdinteger
Consecutive failures per region before that region counts as down, 1–10. Default 2.
tagsstring[]
Up to 10 tags.
contact_idsstring[]
Alert contacts to notify.
response_time_threshold_msinteger | null
Slow-response alert threshold for http/keyword monitors.
httpobject
method, headers (object), body, auth_type (none/basic/bearer), auth_user, auth_pass, follow_redirects, expected_status_codes (e.g. 200-299,301), check_ssl, ssl_expiry_days.
keywordobject
text (required for keyword monitors) and condition (contains or not_contains).
portinteger
Required for port monitors.
dnsobject
record_type (A, AAAA, CNAME, MX, NS, TXT) and optional expected value(s).
heartbeatobject
grace_sec: how late a ping may be before the monitor is down. Default 300.
domainobject
expiry_days: start warning this many days before the registration lapses. Default 30.
Requestbash
curl -X PATCH https://monitermysite.com/api/v1/monitors/cm30… \
  -H "Authorization: Bearer $MMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "interval_sec": 30, "tags": ["prod", "checkout", "tier-1"] }'
Responsejson
{ "object": "monitor", "id": "cm30…", "interval_sec": 30, "tags": ["prod", "checkout", "tier-1"], … }

Delete a monitor

DELETE/v1/monitors/{id}
write scope

Deletes the monitor with its check history and incidents. This cannot be undone.

Requestbash
curl -X DELETE https://monitermysite.com/api/v1/monitors/cm30… \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "monitor", "id": "cm30…", "deleted": true }

Pause a monitor

POST/v1/monitors/{id}/pause
write scope

Stops checks and alerts. Use before a deploy that you know will cause errors, or create a maintenance window to keep the uptime numbers clean.

Requestbash
curl -X POST https://monitermysite.com/api/v1/monitors/cm30…/pause \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "monitor", "id": "cm30…", "active": false, "status": "paused", … }

Resume a monitor

POST/v1/monitors/{id}/resume
write scope

Restarts checks; the first one runs within seconds.

Requestbash
curl -X POST https://monitermysite.com/api/v1/monitors/cm30…/resume \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "monitor", "id": "cm30…", "active": true, "status": "pending", … }

Run a check now

POST/v1/monitors/{id}/check
read scope

Runs the check once from our app server and returns the raw result without touching the monitor's history. Handy for verifying a configuration from CI.

Requestbash
curl -X POST https://monitermysite.com/api/v1/monitors/cm30…/check \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "check_result", "monitor_id": "cm30…", "region": "local", "status": "up", "response_time_ms": 183, "http_status": 200, "error": null, "ssl_days_remaining": 86, "checked_at": "2026-10-09T08:20:11.000Z" }

List checks

GET/v1/monitors/{id}/checks
read scope

Individual check results, newest first. Cursors are check ids. Filter with `region` and `status` (up/down).

Query parameters
limitinteger
Objects per page, 1–100. Default 20.
starting_afterstring
Cursor: the id of the last object on the previous page.
ending_beforestring
Cursor: the id of the first object on the next page (paging backwards).
regionstring
Only checks from this region.
statusenum
up or down.
Requestbash
curl "https://monitermysite.com/api/v1/monitors/cm30…/checks?limit=5" \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "list", "data": [ { "object": "check", "id": "9182734", "region": "fra1", "status": "up", "response_time_ms": 142, "http_status": 200, "error": null, "checked_at": "…" } ], "has_more": true, "url": "/v1/monitors/cm30…/checks" }

Retrieve uptime

GET/v1/monitors/{id}/uptime
read scope

Uptime percentage, check counts and average response time for the last 24 hours, 7, 30 and 90 days, plus one entry per day for 90 days.

Requestbash
curl https://monitermysite.com/api/v1/monitors/cm30…/uptime \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "uptime", "monitor_id": "cm30…", "windows": [ { "label": "24h", "days": 1, "uptime_percent": 100, "checks": 2880, "failures": 0, "avg_response_ms": 151, "downtime_sec": 0 }, … ], "daily": [ { "day": "2026-10-09", "uptime_percent": 100, "downtime_sec": 0, "status": "up" }, … ] }

Incidents

Outages the detection engine opened, with their region timeline.

List incidents

GET/v1/incidents
read scope

Newest first. Filter with `status` (open or resolved) and `monitor_id`.

Query parameters
limitinteger
Objects per page, 1–100. Default 20.
starting_afterstring
Cursor: the id of the last object on the previous page.
ending_beforestring
Cursor: the id of the first object on the next page (paging backwards).
statusenum
open or resolved.
monitor_idstring
Only incidents of this monitor.
Requestbash
curl "https://monitermysite.com/api/v1/incidents?status=open" \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "list", "data": [ { "object": "incident", "id": "cm31…", "monitor_id": "cm30…", "monitor_name": "Checkout API", "status": "open", "cause": "HTTP 503", "regions": ["nyc3", "fra1"], "started_at": "…", "resolved_at": null, "duration_sec": 412, "acknowledged_at": null } ], "has_more": false, "url": "/v1/incidents" }

Retrieve an incident

GET/v1/incidents/{id}
read scope

One incident with its full event timeline (region down/up, acknowledgements, comments).

Requestbash
curl https://monitermysite.com/api/v1/incidents/cm31… \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "incident", "id": "cm31…", "status": "resolved", "events": [ { "type": "started", "message": "…", "region": "nyc3", "created_at": "…" }, { "type": "resolved", … } ], … }

Acknowledge an incident

POST/v1/incidents/{id}/acknowledge
write scope

Marks the incident as being handled and optionally adds a comment. Both appear on the incident timeline.

Body parameters
bystring
Who acknowledged; defaults to the API key's name.
commentstring
Optional note, up to 2000 characters.
Requestbash
curl -X POST https://monitermysite.com/api/v1/incidents/cm31…/acknowledge \
  -H "Authorization: Bearer $MMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "by": "on-call bot", "comment": "Rolling back release 4.2.1" }'
Responsejson
{ "object": "incident", "id": "cm31…", "acknowledged_at": "…", "acknowledged_by": "on-call bot", "comment": "Rolling back release 4.2.1", … }

Alert contacts

Where alerts go. Configurations (webhook URLs, tokens) are write-only: the API never returns them.

List contacts

GET/v1/contacts
read scope

All alert contacts with their type, delivery health and the names of configured fields.

Requestbash
curl https://monitermysite.com/api/v1/contacts \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "list", "data": [ { "object": "contact", "id": "cm32…", "name": "#ops", "type": "slack", "down_only": false, "active": true, "failures": 0, "config_keys": ["webhookUrl"] } ], "has_more": false, "url": "/v1/contacts" }

Create a contact

POST/v1/contacts
write scope

`type` is one of email, webhook, slack, discord, teams, google_chat, telegram, pagerduty (plan-dependent). `config` holds the type's fields: `email`, `url` (webhook), `webhookUrl` (chat apps), `botToken` + `chatId` (Telegram), `integrationKey` (PagerDuty).

Body parameters
namestringrequired
Shown in alerts and the audit log.
typeenumrequired
Channel type.
configobjectrequired
Channel configuration, see above.
down_onlyboolean
Skip recovery notifications. Default false.
Requestbash
curl https://monitermysite.com/api/v1/contacts \
  -H "Authorization: Bearer $MMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "On-call", "type": "pagerduty", "config": { "integrationKey": "R0…" } }'
Responsejson
{ "object": "contact", "id": "cm33…", "name": "On-call", "type": "pagerduty", "config_keys": ["integrationKey"], … }

Delete a contact

DELETE/v1/contacts/{id}
write scope

Removes the contact from every monitor that used it.

Requestbash
curl -X DELETE https://monitermysite.com/api/v1/contacts/cm33… \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "contact", "id": "cm33…", "deleted": true }

Status pages

Read your pages and publish announcements from CI or your incident tooling.

List status pages

GET/v1/status-pages
read scope

Every status page with its components and their current status.

Requestbash
curl https://monitermysite.com/api/v1/status-pages \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "list", "data": [ { "object": "status_page", "id": "cm34…", "name": "Acme status", "slug": "acme", "url": "https://status.acme.com", "components": [ { "id": "…", "monitor_id": "cm30…", "name": "API", "group": "Core", "status": "up" } ] } ], "has_more": false, "url": "/v1/status-pages" }

Retrieve a status page

GET/v1/status-pages/{id}
read scope

One status page by id.

Requestbash
curl https://monitermysite.com/api/v1/status-pages/cm34… \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "status_page", "id": "cm34…", "name": "Acme status", … }

List announcements

GET/v1/status-pages/{id}/announcements
read scope

Incident and maintenance announcements on the page, newest first.

Query parameters
limitinteger
Objects per page, 1–100. Default 20.
starting_afterstring
Cursor: the id of the last object on the previous page.
ending_beforestring
Cursor: the id of the first object on the next page (paging backwards).
Requestbash
curl https://monitermysite.com/api/v1/status-pages/cm34…/announcements \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "list", "data": [ { "object": "announcement", "id": "cm35…", "title": "Elevated error rates", "type": "incident", "status": "resolved", "impact": "minor", … } ], "has_more": false, "url": "…" }

Publish an announcement

POST/v1/status-pages/{id}/announcements
write scope

Publishes an incident or maintenance announcement and e-mails confirmed subscribers. Statuses: investigating, identified, monitoring, resolved (incidents); scheduled, in_progress, completed (maintenance).

Body parameters
titlestringrequired
Headline.
typeenumrequired
incident or maintenance.
statusenumrequired
Initial status, see above.
messagestringrequired
The update text, up to 5000 characters.
impactenum
minor, major or critical. Default minor.
component_idsstring[]
Affected components.
scheduled_fordatetime
Maintenance start (ISO 8601).
scheduled_untildatetime
Maintenance end.
Requestbash
curl https://monitermysite.com/api/v1/status-pages/cm34…/announcements \
  -H "Authorization: Bearer $MMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Database maintenance", "type": "maintenance", "status": "scheduled", "message": "Writes pause for ~5 minutes.", "scheduled_for": "2026-10-12T02:00:00Z", "scheduled_until": "2026-10-12T02:30:00Z" }'
Responsejson
HTTP/1.1 201 Created

{ "object": "announcement", "id": "cm36…", "title": "Database maintenance", "type": "maintenance", "status": "scheduled", … }

Maintenance windows

Silence alerts and exclude planned work from uptime. Create one from your deploy pipeline, delete it when the deploy ends.

List maintenance windows

GET/v1/maintenance-windows
read scope

All windows, latest start first.

Requestbash
curl https://monitermysite.com/api/v1/maintenance-windows \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "list", "data": [ { "object": "maintenance_window", "id": "cm37…", "name": "Release 4.3", "monitor_ids": [], "starts_at": "…", "ends_at": "…", "recurrence": "none" } ], "has_more": false, "url": "/v1/maintenance-windows" }

Create a maintenance window

POST/v1/maintenance-windows
write scope

An empty `monitor_ids` list covers every monitor. `recurrence` is none, daily, weekly or monthly.

Body parameters
namestringrequired
Label.
starts_atdatetimerequired
ISO 8601 with offset, e.g. 2026-10-12T02:00:00Z.
ends_atdatetimerequired
Must be after starts_at.
monitor_idsstring[]
Default [] = all monitors.
recurrenceenum
Default none.
Requestbash
curl https://monitermysite.com/api/v1/maintenance-windows \
  -H "Authorization: Bearer $MMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Release 4.3", "starts_at": "2026-10-12T02:00:00Z", "ends_at": "2026-10-12T02:30:00Z" }'
Responsejson
HTTP/1.1 201 Created

{ "object": "maintenance_window", "id": "cm37…", "name": "Release 4.3", "recurrence": "none", … }

Delete a maintenance window

DELETE/v1/maintenance-windows/{id}
write scope

Ends the window immediately.

Requestbash
curl -X DELETE https://monitermysite.com/api/v1/maintenance-windows/cm37… \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "maintenance_window", "id": "cm37…", "deleted": true }

Regions

The probe locations and their source addresses.

List regions

GET/v1/regions
read scope

Live regions with city, country and the IP addresses checks come from, for allowlisting.

Requestbash
curl https://monitermysite.com/api/v1/regions \
  -H "Authorization: Bearer $MMS_API_KEY"
Responsejson
{ "object": "list", "data": [ { "object": "region", "code": "nyc3", "name": "New York", "city": "New York", "country": "United States", "continent": "North America", "ips": ["134.209.175.29", "138.197.70.1"] }, … ], "has_more": false, "url": "/v1/regions" }

Need an endpoint we do not have yet?

Tell us what you are building and we will add it. Most requests ship within a week.

Email support