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.
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.
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.
| type | Status | Meaning |
|---|---|---|
| authentication_error | 401 | No 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_error | 403 | The key is read-only and the endpoint writes (insufficient_scope). |
| plan_limit_error | 403 | A plan limit was reached (monitors, interval, regions, status pages, channels). upgrade_to names the plan that lifts it. |
| invalid_request_error | 400 / 415 | Validation failed; param names the field. code is parameter_missing, parameter_invalid, invalid_json or unsupported_media_type. |
| not_found_error | 404 | The object does not exist in this workspace. |
| idempotency_error | 400 | An Idempotency-Key was reused for a different request. |
| rate_limit_error | 429 | Too many requests this minute; Retry-After says how long to wait. |
| api_error | 500 | Something failed on our side. Quote X-Request-Id when you contact support. |
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.
| Plan | Requests / minute | Active API keys |
|---|---|---|
| Starter | 60 | 2 |
| Launch | 300 | 5 |
| Growth | 600 | 20 |
| Summit | 1,200 | 50 |
X-RateLimit-Limit: 600 X-RateLimit-Remaining: 597 X-RateLimit-Reset: 1760000460 Retry-After: 23 # only on 429
Pagination
List endpoints return up to limit objects (default 20, maximum 100). Pass the id of the last object you received as starting_after to get the next page, or the first id as ending_before to page backwards. has_more tells you when to stop.
GET /v1/monitors?limit=2
{
"object": "list",
"data": [ { "object": "monitor", "id": "cm2z…", … }, { "object": "monitor", "id": "cm30…", … } ],
"has_more": true,
"url": "/v1/monitors"
}
# next page
GET /v1/monitors?limit=2&starting_after=cm30…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.
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.
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
/v1/accountReturns 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.
curl https://monitermysite.com/api/v1/account \ -H "Authorization: Bearer $MMS_API_KEY"
{
"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
/v1/monitorsAll monitors in the workspace, oldest first. Filter with `type`, `status` (up, down, paused, pending, maintenance), `tag` and `q` (matches name or target).
Query parameterslimitinteger- 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.
curl "https://monitermysite.com/api/v1/monitors?status=down&limit=50" \ -H "Authorization: Bearer $MMS_API_KEY"
{
"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
/v1/monitorsCreates 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 parametersnamestringrequired- Display name, up to 100 characters.
typeenumrequiredhttp,keyword,ping,port,dns,ssl,heartbeatordomain. 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.
httpobjectmethod,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.keywordobjecttext(required for keyword monitors) andcondition(containsornot_contains).portinteger- Required for port monitors.
dnsobjectrecord_type(A, AAAA, CNAME, MX, NS, TXT) and optionalexpectedvalue(s).heartbeatobjectgrace_sec: how late a ping may be before the monitor is down. Default 300.domainobjectexpiry_days: start warning this many days before the registration lapses. Default 30.
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"]
}'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
/v1/monitors/{id}One monitor by id, including its last check and expiry information for SSL and domain monitors.
curl https://monitermysite.com/api/v1/monitors/cm30… \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "monitor", "id": "cm30…", "name": "Checkout API", "status": "up", "ssl": { "expires_at": "2027-01-04T00:00:00.000Z", "expiry_days": 14 }, … }Update a monitor
/v1/monitors/{id}Partial update: only the fields you send change. `type` cannot be changed. The next check runs immediately after the update.
Body parametersnamestringrequired- 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.
httpobjectmethod,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.keywordobjecttext(required for keyword monitors) andcondition(containsornot_contains).portinteger- Required for port monitors.
dnsobjectrecord_type(A, AAAA, CNAME, MX, NS, TXT) and optionalexpectedvalue(s).heartbeatobjectgrace_sec: how late a ping may be before the monitor is down. Default 300.domainobjectexpiry_days: start warning this many days before the registration lapses. Default 30.
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"] }'{ "object": "monitor", "id": "cm30…", "interval_sec": 30, "tags": ["prod", "checkout", "tier-1"], … }Delete a monitor
/v1/monitors/{id}Deletes the monitor with its check history and incidents. This cannot be undone.
curl -X DELETE https://monitermysite.com/api/v1/monitors/cm30… \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "monitor", "id": "cm30…", "deleted": true }Pause a monitor
/v1/monitors/{id}/pauseStops checks and alerts. Use before a deploy that you know will cause errors, or create a maintenance window to keep the uptime numbers clean.
curl -X POST https://monitermysite.com/api/v1/monitors/cm30…/pause \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "monitor", "id": "cm30…", "active": false, "status": "paused", … }Resume a monitor
/v1/monitors/{id}/resumeRestarts checks; the first one runs within seconds.
curl -X POST https://monitermysite.com/api/v1/monitors/cm30…/resume \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "monitor", "id": "cm30…", "active": true, "status": "pending", … }Run a check now
/v1/monitors/{id}/checkRuns 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.
curl -X POST https://monitermysite.com/api/v1/monitors/cm30…/check \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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
/v1/monitors/{id}/checksIndividual check results, newest first. Cursors are check ids. Filter with `region` and `status` (up/down).
Query parameterslimitinteger- 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.
statusenumupordown.
curl "https://monitermysite.com/api/v1/monitors/cm30…/checks?limit=5" \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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
/v1/monitors/{id}/uptimeUptime 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.
curl https://monitermysite.com/api/v1/monitors/cm30…/uptime \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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
/v1/incidentsNewest first. Filter with `status` (open or resolved) and `monitor_id`.
Query parameterslimitinteger- 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).
statusenumopenorresolved.monitor_idstring- Only incidents of this monitor.
curl "https://monitermysite.com/api/v1/incidents?status=open" \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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
/v1/incidents/{id}One incident with its full event timeline (region down/up, acknowledgements, comments).
curl https://monitermysite.com/api/v1/incidents/cm31… \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "incident", "id": "cm31…", "status": "resolved", "events": [ { "type": "started", "message": "…", "region": "nyc3", "created_at": "…" }, { "type": "resolved", … } ], … }Acknowledge an incident
/v1/incidents/{id}/acknowledgeMarks the incident as being handled and optionally adds a comment. Both appear on the incident timeline.
Body parametersbystring- Who acknowledged; defaults to the API key's name.
commentstring- Optional note, up to 2000 characters.
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" }'{ "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
/v1/contactsAll alert contacts with their type, delivery health and the names of configured fields.
curl https://monitermysite.com/api/v1/contacts \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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
/v1/contacts`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 parametersnamestringrequired- Shown in alerts and the audit log.
typeenumrequired- Channel type.
configobjectrequired- Channel configuration, see above.
down_onlyboolean- Skip recovery notifications. Default false.
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…" } }'{ "object": "contact", "id": "cm33…", "name": "On-call", "type": "pagerduty", "config_keys": ["integrationKey"], … }Delete a contact
/v1/contacts/{id}Removes the contact from every monitor that used it.
curl -X DELETE https://monitermysite.com/api/v1/contacts/cm33… \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "contact", "id": "cm33…", "deleted": true }Status pages
Read your pages and publish announcements from CI or your incident tooling.
List status pages
/v1/status-pagesEvery status page with its components and their current status.
curl https://monitermysite.com/api/v1/status-pages \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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
/v1/status-pages/{id}One status page by id.
curl https://monitermysite.com/api/v1/status-pages/cm34… \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "status_page", "id": "cm34…", "name": "Acme status", … }List announcements
/v1/status-pages/{id}/announcementsIncident and maintenance announcements on the page, newest first.
Query parameterslimitinteger- 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).
curl https://monitermysite.com/api/v1/status-pages/cm34…/announcements \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "list", "data": [ { "object": "announcement", "id": "cm35…", "title": "Elevated error rates", "type": "incident", "status": "resolved", "impact": "minor", … } ], "has_more": false, "url": "…" }Publish an announcement
/v1/status-pages/{id}/announcementsPublishes an incident or maintenance announcement and e-mails confirmed subscribers. Statuses: investigating, identified, monitoring, resolved (incidents); scheduled, in_progress, completed (maintenance).
Body parameterstitlestringrequired- Headline.
typeenumrequiredincidentormaintenance.statusenumrequired- Initial status, see above.
messagestringrequired- The update text, up to 5000 characters.
impactenumminor,majororcritical. Default minor.component_idsstring[]- Affected components.
scheduled_fordatetime- Maintenance start (ISO 8601).
scheduled_untildatetime- Maintenance end.
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" }'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
/v1/maintenance-windowsAll windows, latest start first.
curl https://monitermysite.com/api/v1/maintenance-windows \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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
/v1/maintenance-windowsAn empty `monitor_ids` list covers every monitor. `recurrence` is none, daily, weekly or monthly.
Body parametersnamestringrequired- 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.
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" }'HTTP/1.1 201 Created
{ "object": "maintenance_window", "id": "cm37…", "name": "Release 4.3", "recurrence": "none", … }Delete a maintenance window
/v1/maintenance-windows/{id}Ends the window immediately.
curl -X DELETE https://monitermysite.com/api/v1/maintenance-windows/cm37… \ -H "Authorization: Bearer $MMS_API_KEY"
{ "object": "maintenance_window", "id": "cm37…", "deleted": true }Regions
The probe locations and their source addresses.
List regions
/v1/regionsLive regions with city, country and the IP addresses checks come from, for allowlisting.
curl https://monitermysite.com/api/v1/regions \ -H "Authorization: Bearer $MMS_API_KEY"
{ "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.