Heedery API
Everything the dashboard does, over HTTPS: list and change monitors, follow incidents, plan maintenance and mark deploys. Plain REST with predictable URLs, JSON bodies and the usual status codes.
- Auth
Authorization: Bearer hda_…- Format
- JSON in and out, UTF-8. Times are ISO 8601 in UTC.
- Spec
- OpenAPI · v1.0.0 · openapi.json
https://heedery.com/api/v1Your first request
Thirty seconds, three steps.
- 01Make a tokenIn the dashboard open Settings → Integrations and create one in the API section. Pro and up can make read tokens; Team and up can also make write tokens. It is shown once and starts with
hda_. - 02Keep it in the environment
export HEEDERY_TOKEN=hda_…Every sample on this page reads it from there. - 03Ask for somethingRun the sample in your language. It answers with the state of every monitor in the workspace.
{
"workspace": {
"id": "cmh3k2x9a0000qv08wksp0001",
"name": "Acme"
},
"generatedAt": "2026-11-10T09:30:00.000Z",
"sites": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop",
"url": "https://shop.example.com/",
"kind": "web",
"enabled": true,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null
}
]
}Use it from Claude, Cursor or VS Code
Heedery runs an MCP server at https://heedery.com/api/mcp, so an assistant can answer “what went down last night?” from your real data, and with a write token pause a monitor or acknowledge an incident when you ask it to.
claude.ai needs no token: in Settings → Connectors → Add custom connector, paste https://heedery.com/api/mcp, press Connect, sign in to Heedery, pick the workspace and read or write, and allow it. Claude Desktop and mobile share the connector. Claude Code, Cursor and VS Code sign in the same way: add the server by its URL alone and they open Heedery to ask you. Cursor gets the code back through its own cursor:// link.
Clients that do not sign in take the same tokens and scopes as the API, in the Authorization header. Give it a read token if all you want is answers.
For client authors: a 401 points at https://heedery.com/.well-known/oauth-protected-resource/api/mcp; then a Client ID Metadata Document (an https client_id, fetched with no redirects, 5 seconds and 5 KB at most) or dynamic registration, the authorization code flow with PKCE (S256) and the resource parameter. Redirect URIs are https, http on localhost on any port, or an app’s own scheme such as com.example.app:/callback. Access tokens last an hour and refresh tokens rotate on every use.
# Settings → Connectors → Add custom connector
# Name: Heedery
# URL: https://heedery.com/api/mcp
# then Connect, sign in, Allow# Sign in: add it, then /mcp → Authenticate
claude mcp add --transport http heedery https://heedery.com/api/mcp
# Or with a token
claude mcp add --transport http heedery https://heedery.com/api/mcp \
--header "Authorization: Bearer $HEEDERY_TOKEN"{
"mcpServers": {
"heedery": {
"url": "https://heedery.com/api/mcp"
}
}
}{
"servers": {
"heedery": {
"type": "http",
"url": "https://heedery.com/api/mcp"
}
}
}Authentication
Send the token in the Authorization header as Bearer hda_…. A request without one, or with one that was rotated or deleted, gets 401.
A token belongs to one workspace and sees all of it. Keep it out of code and browsers: anyone holding it can do what its scope allows. Rotating it in the API section of Settings → Integrations stops the old one at once.
Scopes
- read
- Every GET: monitors, incidents, maintenance, deploys, status.Pro and up
- write
- Also creates, changes and deletes: pause, acknowledge, schedule, mark deploys.Team and up
- public
- 1 endpoints.Starter and up
A read token calling a write endpoint gets 403, as does any token once the plan no longer includes the API.
curl https://heedery.com/api/v1/monitors \
-H "Authorization: Bearer $HEEDERY_TOKEN"Errors
A 2xx status means it worked. Anything else comes with the same body: an error object whose code is stable enough to branch on and whose message is written for people.
5xx answers are ours and safe to retry; use an idempotency key on POSTs so a retry never does the work twice.
The error object
codestringrequiredStable, machine-readable reason. Branch on this, not on the message.messagestringrequiredWhat went wrong, in a sentence for people.detailsanyExtra facts where they help: the fields that failed validation, the scope or plan needed.
Codes
- invalid_request
- validation_failed
- unauthorized
- forbidden
- scope_required
- plan_required
- needs_plan
- monitor_limit_reached
- browser_limit_reached
- interval_below_plan
- not_found
- incident_resolved
- not_running
- not_upcoming
- window_closed
- idempotency_key_reused
- idempotency_in_progress
- rate_limited
- internal_error
Pagination
Lists come a page at a time as { data, nextCursor }. Pass nextCursor back as cursor for the next page; it is null on the last one.
Cursors keep their place when items are added while you read, so nothing is skipped or seen twice. Treat them as opaque: they may change shape.
Parameters on every list
cursorstringThenextCursorof the previous page; leave out for the first page. Opaque: do not build or parse it.limitintegerHow many items to return, 1 to 100.Default
501 to 100
let cursor = null;
do {
const url = new URL('https://heedery.com/api/v1/monitors');
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('cursor', cursor);
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.HEEDERY_TOKEN}` },
});
const page = await res.json();
for (const item of page.data) console.log(item.id);
cursor = page.nextCursor;
} while (cursor);Idempotency
Networks drop answers. To retry a POST without doing it twice, send an Idempotency-Key header with a value of your own, a UUID say. A second request with the same key gets the first one’s answer back instead of running again.
Reusing a key with a different body is a 422; a retry while the first request still runs is a 409. GET, PATCH and DELETE are safe to repeat as they are.
Header
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
curl -X POST https://heedery.com/api/v1/deploys \
-H "Authorization: Bearer $HEEDERY_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: <Idempotency-Key>' \
-d '{
"version": "v1.4.2",
"commit": "9f2c1ab",
"environment": "production",
"monitors": [
"shop.example.com"
]
}'Rate limits
Each token has a budget of requests per minute, reads and writes counted apart, set by the workspace’s plan. Every answer says how much of it is left; past it the API answers 429 with a Retry-After until the minute is over. MCP tool calls count against the same budget.
Polling for status? One status call covers every monitor, so a dashboard needs a single request per refresh.
Per token, by plan
| Plan | Reads a minute | Writes a minute |
|---|---|---|
| Pro | 120 | — read-only |
| Team | 300 | 60 |
| Agency, Enterprise | 600 | 120 |
Headers
- RateLimit-Limit
- Requests of this kind (reads or writes) this token may make per minute, set by the workspace’s plan.
- RateLimit-Remaining
- Requests left in the current minute.
- RateLimit-Reset
- Seconds until the window resets.
- Retry-After
- Seconds to wait before trying again.
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 42
Retry-After: 42The monitor object
A monitor: a site, API, server or heartbeat Heedery checks.
Attributes
idstringrequiredThe monitor.namestringrequireddescriptionstring · nullablerequiredtypestringrequiredHow the monitor checks:http(a web page or API),tcp(a port),dns(a record),ping,udp,mail(SMTP, IMAP or POP3),browser(a browser flow: scripted steps in a real browser) orheartbeat(your job pings us; we alert when the pings stop).One of
httptcpdnspingudpmailbrowserheartbeatkindstringrequiredWhat it is: a website, an API or a heartbeat. Picks the icon and the defaults (an API counts a response slower than 2 s as down).One of
webapiheartbeaturlstringrequiredThe target:https://…for http,tcp://host:port,dns://hostname,ping://host,udp://host:port,smtp|imap|pop3://host:portfor mail,heartbeat://namefor a heartbeat.enabledbooleanrequiredFalse while paused.pausedByPlanbooleanrequiredPaused because a plan change left more monitors than the plan allows.statestringrequiredThe state the Overview shows:up;down(an open incident or a failed last check);paused;unknown(no check yet, or the checker stopped reporting);maintenance(inside a maintenance window: alerts are held);blocked(a bot wall answered instead of the site, so it is up but we cannot see it).One of
updownpausedunknownmaintenanceblockedcheckedAtstring (ISO 8601) · nullablerequiredWhen the last check ran.latencyMsinteger · nullablerequiredResponse time of the last check.statusCodeinteger · nullablerequiredHTTP status of the last check.errorstring · nullablerequiredWhy the last check failed.incidentobject · nullablerequiredThe open incident, if the monitor is down.Show 3 child fieldsHide 3 child fields
idstringrequiredThe open incident.startedAtstring (ISO 8601)requiredThe first failed check.errorstring · nullablerequired
checkIntervalintegerrequiredMinutes between checks; for a heartbeat, the period between pings.alertAfterMinutesintegerrequiredMinutes it may stay down before an incident opens and anyone is told; 0 = at once.categoryIdstring · nullablerequiredcategoryobject · nullablerequiredThe category it is filed under (agencies often use one per client).Show 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
statusPageIdstring · nullablerequiredescalationPolicyIdstring · nullablerequiredWho is paged and when; null = the workspace default.pinnedbooleanrequiredhttpMethodstringrequiredOne of
GETHEADPOSTPUTPATCHDELETErequestHeadersarray of objects · nullablerequiredHeaders the check sends. A read-only token sees the names with the values hidden.Show 2 child fieldsHide 2 child fields
namestringrequiredup to 100 characters
valuestringrequiredup to 2000 characters
requestBodystring · nullablerequiredkeywordstring · nullablerequiredkeywordModestringrequiredOne of
containsabsentjsonPathstring · nullablerequiredjsonExpectedstring · nullablerequiredexpectedStatusCodesstring · nullablerequiredCodes that count as up, like200-299,404; null = 200-399.maxLatencyMsinteger · nullablerequiredA slower response counts as down; null = only the timeout.dnsRecordTypestringrequiredOne of
AAAAACNAMEMXTXTdnsExpectedstring · nullablerequiredpingMaxLossinteger · nullablerequiredudpPayloadstring · nullablerequiredudpPayloadFormatstringrequiredOne of
texthexudpExpectedstring · nullablerequiredmailTlsstringrequiredOne of
nonestarttlstlsheartbeatGraceintegerrequiredHeartbeat: minutes of grace on top of the period.heartbeatUrlstring · nullablerequiredHeartbeat: the URL your job calls. Only tokens with the write scope see it (it is a secret: anyone with it can ping).checkSslbooleanrequiredcheckDomainExpirybooleanrequiredsslobject · nullablerequiredShow 2 child fieldsHide 2 child fields
validboolean · nullablerequiredexpiresAtstring (ISO 8601) · nullablerequiredWhen the certificate expires.
domainExpiresAtstring (ISO 8601) · nullablerequiredWhen the domain registration ends.emailAlertsbooleanrequiredalertEmailsstring · nullablerequiredExtra alert recipients, comma separated.expiryAlertsbooleanrequiredcreatedAtstring (ISO 8601)requiredWhen it was added.updatedAtstring (ISO 8601)requiredWhen it last changed.linksobjectrequiredShow 1 child fieldHide 1 child field
monitorstringrequiredThe monitor in the Heedery app (needs a sign-in).
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"description": null,
"type": "http",
"kind": "web",
"url": "https://shop.example.com/checkout",
"enabled": true,
"pausedByPlan": false,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null,
"checkInterval": 1,
"alertAfterMinutes": 0,
"categoryId": "cmh3k2x9a0002qv08cat00001",
"category": {
"id": "cmh3k2x9a0002qv08cat00001",
"name": "Acme Ltd"
},
"statusPageId": "cmh3k2x9a0003qv08page0001",
"escalationPolicyId": null,
"pinned": false,
"httpMethod": "GET",
"requestHeaders": null,
"requestBody": null,
"keyword": "Pay now",
"keywordMode": "contains",
"jsonPath": null,
"jsonExpected": null,
"expectedStatusCodes": null,
"maxLatencyMs": null,
"dnsRecordType": "A",
"dnsExpected": null,
"pingMaxLoss": null,
"udpPayload": null,
"udpPayloadFormat": "text",
"udpExpected": null,
"mailTls": "starttls",
"heartbeatGrace": 5,
"heartbeatUrl": null,
"checkSsl": true,
"checkDomainExpiry": false,
"ssl": {
"valid": true,
"expiresAt": "2027-01-20T23:59:59.000Z"
},
"domainExpiresAt": null,
"emailAlerts": true,
"alertEmails": null,
"expiryAlerts": true,
"createdAt": "2026-10-01T08:00:00.000Z",
"updatedAt": "2026-11-09T14:12:00.000Z",
"links": {
"monitor": "https://heedery.com/admin/sites/cmh3k2x9a0001qv08abcd1234"
}
}List monitors
GET/monitors
Every monitor of the workspace, oldest first, with its current state and last check. Filter by state, type, category or a search term; page with cursor.
Needs: any token (read scope), on the Pro plan or above.
Query parameters
statusstringOne of
updownpausedunknownmaintenanceblockedtypestringOne of
httptcpdnspingudpmailbrowserheartbeatcategorystringup to 100 characters
qstringup to 200 characters
limitintegerHow many items to return, 1 to 100.Default
501 to 100cursorstringThenextCursorof the previous page; leave out for the first page. Opaque: do not build or parse it.
Returns
200A page of monitors.
Show the response fieldsHide the response fields
dataarray of objectsrequiredShow 49 child fieldsHide 49 child fields
idstringrequiredThe monitor.namestringrequireddescriptionstring · nullablerequiredtypestringrequiredHow the monitor checks:http(a web page or API),tcp(a port),dns(a record),ping,udp,mail(SMTP, IMAP or POP3),browser(a browser flow: scripted steps in a real browser) orheartbeat(your job pings us; we alert when the pings stop).One of
httptcpdnspingudpmailbrowserheartbeatkindstringrequiredWhat it is: a website, an API or a heartbeat. Picks the icon and the defaults (an API counts a response slower than 2 s as down).One of
webapiheartbeaturlstringrequiredThe target:https://…for http,tcp://host:port,dns://hostname,ping://host,udp://host:port,smtp|imap|pop3://host:portfor mail,heartbeat://namefor a heartbeat.enabledbooleanrequiredFalse while paused.pausedByPlanbooleanrequiredPaused because a plan change left more monitors than the plan allows.statestringrequiredThe state the Overview shows:up;down(an open incident or a failed last check);paused;unknown(no check yet, or the checker stopped reporting);maintenance(inside a maintenance window: alerts are held);blocked(a bot wall answered instead of the site, so it is up but we cannot see it).One of
updownpausedunknownmaintenanceblockedcheckedAtstring (ISO 8601) · nullablerequiredWhen the last check ran.latencyMsinteger · nullablerequiredResponse time of the last check.statusCodeinteger · nullablerequiredHTTP status of the last check.errorstring · nullablerequiredWhy the last check failed.incidentobject · nullablerequiredThe open incident, if the monitor is down.Show 3 child fieldsHide 3 child fields
idstringrequiredThe open incident.startedAtstring (ISO 8601)requiredThe first failed check.errorstring · nullablerequired
checkIntervalintegerrequiredMinutes between checks; for a heartbeat, the period between pings.alertAfterMinutesintegerrequiredMinutes it may stay down before an incident opens and anyone is told; 0 = at once.categoryIdstring · nullablerequiredcategoryobject · nullablerequiredThe category it is filed under (agencies often use one per client).Show 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
statusPageIdstring · nullablerequiredescalationPolicyIdstring · nullablerequiredWho is paged and when; null = the workspace default.pinnedbooleanrequiredhttpMethodstringrequiredOne of
GETHEADPOSTPUTPATCHDELETErequestHeadersarray of objects · nullablerequiredHeaders the check sends. A read-only token sees the names with the values hidden.Show 2 child fieldsHide 2 child fields
namestringrequiredup to 100 characters
valuestringrequiredup to 2000 characters
requestBodystring · nullablerequiredkeywordstring · nullablerequiredkeywordModestringrequiredOne of
containsabsentjsonPathstring · nullablerequiredjsonExpectedstring · nullablerequiredexpectedStatusCodesstring · nullablerequiredCodes that count as up, like200-299,404; null = 200-399.maxLatencyMsinteger · nullablerequiredA slower response counts as down; null = only the timeout.dnsRecordTypestringrequiredOne of
AAAAACNAMEMXTXTdnsExpectedstring · nullablerequiredpingMaxLossinteger · nullablerequiredudpPayloadstring · nullablerequiredudpPayloadFormatstringrequiredOne of
texthexudpExpectedstring · nullablerequiredmailTlsstringrequiredOne of
nonestarttlstlsheartbeatGraceintegerrequiredHeartbeat: minutes of grace on top of the period.heartbeatUrlstring · nullablerequiredHeartbeat: the URL your job calls. Only tokens with the write scope see it (it is a secret: anyone with it can ping).checkSslbooleanrequiredcheckDomainExpirybooleanrequiredsslobject · nullablerequiredShow 2 child fieldsHide 2 child fields
validboolean · nullablerequiredexpiresAtstring (ISO 8601) · nullablerequiredWhen the certificate expires.
domainExpiresAtstring (ISO 8601) · nullablerequiredWhen the domain registration ends.emailAlertsbooleanrequiredalertEmailsstring · nullablerequiredExtra alert recipients, comma separated.expiryAlertsbooleanrequiredcreatedAtstring (ISO 8601)requiredWhen it was added.updatedAtstring (ISO 8601)requiredWhen it last changed.linksobjectrequiredShow 1 child fieldHide 1 child field
monitorstringrequiredThe monitor in the Heedery app (needs a sign-in).
nextCursorstring · nullablerequiredPass ascursorto get the next page; null on the last page.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"data": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"description": null,
"type": "http",
"kind": "web",
"url": "https://shop.example.com/checkout",
"enabled": true,
"pausedByPlan": false,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null,
"checkInterval": 1,
"alertAfterMinutes": 0,
"categoryId": "cmh3k2x9a0002qv08cat00001",
"category": {
"id": "cmh3k2x9a0002qv08cat00001",
"name": "Acme Ltd"
},
"statusPageId": "cmh3k2x9a0003qv08page0001",
"escalationPolicyId": null,
"pinned": false,
"httpMethod": "GET",
"requestHeaders": null,
"requestBody": null,
"keyword": "Pay now",
"keywordMode": "contains",
"jsonPath": null,
"jsonExpected": null,
"expectedStatusCodes": null,
"maxLatencyMs": null,
"dnsRecordType": "A",
"dnsExpected": null,
"pingMaxLoss": null,
"udpPayload": null,
"udpPayloadFormat": "text",
"udpExpected": null,
"mailTls": "starttls",
"heartbeatGrace": 5,
"heartbeatUrl": null,
"checkSsl": true,
"checkDomainExpiry": false,
"ssl": {
"valid": true,
"expiresAt": "2027-01-20T23:59:59.000Z"
},
"domainExpiresAt": null,
"emailAlerts": true,
"alertEmails": null,
"expiryAlerts": true,
"createdAt": "2026-10-01T08:00:00.000Z",
"updatedAt": "2026-11-09T14:12:00.000Z",
"links": {
"monitor": "https://heedery.com/admin/sites/cmh3k2x9a0001qv08abcd1234"
}
}
],
"nextCursor": null
}Create a monitor
POST/monitors
Adds a monitor, checked from the next minute. The same rules as the app apply: your plan’s monitor count and shortest interval, browser flows per plan, and no private or internal targets. Send an Idempotency-Key so a retry cannot add it twice.
Needs: a token with the write scope, on the Team plan or above.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Body
JSONnamestringrequired1 to 200 characters
typestringHow the monitor checks:http(a web page or API),tcp(a port),dns(a record),ping,udp,mail(SMTP, IMAP or POP3),browser(a browser flow: scripted steps in a real browser) orheartbeat(your job pings us; we alert when the pings stop).One of
httptcpdnspingudpmailbrowserheartbeatDefault
httpkindstringFor checks other than heartbeats:web(default) orapi. An API counts a response slower than 2 s as down unless you set maxLatencyMs.One of
webapiurlstringThe target, required except for heartbeats:https://shop.example.com,db.example.com:5432(tcp),example.com(dns, ping),ntp.example.com:123(udp),smtp://mail.example.com:587(mail). Private and internal addresses are refused.up to 2000 characters
descriptionstring · nullableup to 2000 characters
enabledbooleanFalse to create it paused. On update, prefer /pause and /resume.checkIntervalintegerMinutes between checks, 1 to 10080 (15 by default). Your plan sets the floor (Starter 10, others 1); browser flows run at most every 5.1 to 10080
alertAfterMinutesintegerMinutes it may stay down before an incident opens, 0 to 30 (0 by default).0 to 30
categoryIdstring · nullablestatusPageIdstring · nullableThe status page it shows on. Left out or null, it is on no page: a new monitor is never published by itself.escalationPolicyIdstring · nullablehttpMethodstringOne of
GETHEADPOSTPUTPATCHDELETErequestHeadersarray of objects · nullableup to 20 items
Show 2 child fieldsHide 2 child fields
namestringrequiredup to 100 characters
valuestringrequiredup to 2000 characters
requestBodystring · nullableup to 10000 characters
keywordstring · nullableText the response must contain (or must not).up to 500 characters
keywordModestringOne of
containsabsentjsonPathstring · nullableA dot path into a JSON response, likestatusorchecks.db.up to 200 characters
jsonExpectedstring · nullableup to 500 characters
expectedStatusCodesstring · nullableup to 200 characters
maxLatencyMsinteger · nullable50 to 60000
dnsRecordTypestringOne of
AAAAACNAMEMXTXTdnsExpectedstring · nullableup to 500 characters
pingMaxLossinteger · nullable0 to 99
udpPayloadstring · nullableup to 4000 characters
udpPayloadFormatstringOne of
texthexudpExpectedstring · nullableup to 500 characters
mailTlsstringOne of
nonestarttlstlsheartbeatGraceinteger0 to 1440
browserStepsarray of objectsBrowser flows: the scenario, the steps as the app’s editor saves them ({ "type": "goto", "url": "https://…" },click,fill,expect_text…). The firstgotoURL becomes the monitor’s url.up to 20 items
checkSslbooleancheckDomainExpirybooleanemailAlertsbooleanalertEmailsstring · nullableup to 2000 characters
Returns
201The new monitor: a monitor object.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.);monitor_limit_reached(The plan’s monitors are all in use.);interval_below_plan(The plan does not check that often.);browser_limit_reached(The plan’s browser flows are all in use.);needs_plan(The workspace has no plan, so it runs no monitors.) - 409
- Conflict:
idempotency_in_progress(A request with this Idempotency-Key is still running.) - 422
- Unprocessable:
validation_failed(A field is wrong;detailslists them.);idempotency_key_reused(The Idempotency-Key was used with a different request.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"description": null,
"type": "http",
"kind": "web",
"url": "https://shop.example.com/checkout",
"enabled": true,
"pausedByPlan": false,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null,
"checkInterval": 1,
"alertAfterMinutes": 0,
"categoryId": "cmh3k2x9a0002qv08cat00001",
"category": {
"id": "cmh3k2x9a0002qv08cat00001",
"name": "Acme Ltd"
},
"statusPageId": "cmh3k2x9a0003qv08page0001",
"escalationPolicyId": null,
"pinned": false,
"httpMethod": "GET",
"requestHeaders": null,
"requestBody": null,
"keyword": "Pay now",
"keywordMode": "contains",
"jsonPath": null,
"jsonExpected": null,
"expectedStatusCodes": null,
"maxLatencyMs": null,
"dnsRecordType": "A",
"dnsExpected": null,
"pingMaxLoss": null,
"udpPayload": null,
"udpPayloadFormat": "text",
"udpExpected": null,
"mailTls": "starttls",
"heartbeatGrace": 5,
"heartbeatUrl": null,
"checkSsl": true,
"checkDomainExpiry": false,
"ssl": {
"valid": true,
"expiresAt": "2027-01-20T23:59:59.000Z"
},
"domainExpiresAt": null,
"emailAlerts": true,
"alertEmails": null,
"expiryAlerts": true,
"createdAt": "2026-10-01T08:00:00.000Z",
"updatedAt": "2026-11-09T14:12:00.000Z",
"links": {
"monitor": "https://heedery.com/admin/sites/cmh3k2x9a0001qv08abcd1234"
}
}Get a monitor
GET/monitors/{id}
One monitor with its settings, state and last check. For uptime and response times over time, see /monitors/{id}/metrics.
Needs: any token (read scope), on the Pro plan or above.
Path parameters
idstringrequiredThe record id.
Returns
200The monitor: a monitor object.
- 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"description": null,
"type": "http",
"kind": "web",
"url": "https://shop.example.com/checkout",
"enabled": true,
"pausedByPlan": false,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null,
"checkInterval": 1,
"alertAfterMinutes": 0,
"categoryId": "cmh3k2x9a0002qv08cat00001",
"category": {
"id": "cmh3k2x9a0002qv08cat00001",
"name": "Acme Ltd"
},
"statusPageId": "cmh3k2x9a0003qv08page0001",
"escalationPolicyId": null,
"pinned": false,
"httpMethod": "GET",
"requestHeaders": null,
"requestBody": null,
"keyword": "Pay now",
"keywordMode": "contains",
"jsonPath": null,
"jsonExpected": null,
"expectedStatusCodes": null,
"maxLatencyMs": null,
"dnsRecordType": "A",
"dnsExpected": null,
"pingMaxLoss": null,
"udpPayload": null,
"udpPayloadFormat": "text",
"udpExpected": null,
"mailTls": "starttls",
"heartbeatGrace": 5,
"heartbeatUrl": null,
"checkSsl": true,
"checkDomainExpiry": false,
"ssl": {
"valid": true,
"expiresAt": "2027-01-20T23:59:59.000Z"
},
"domainExpiresAt": null,
"emailAlerts": true,
"alertEmails": null,
"expiryAlerts": true,
"createdAt": "2026-10-01T08:00:00.000Z",
"updatedAt": "2026-11-09T14:12:00.000Z",
"links": {
"monitor": "https://heedery.com/admin/sites/cmh3k2x9a0001qv08abcd1234"
}
}Update a monitor
PATCH/monitors/{id}
Changes the fields you send and keeps the rest. Changing type or url re-checks the target the way the app does.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Body
JSONnamestring1 to 200 characters
typestringHow the monitor checks:http(a web page or API),tcp(a port),dns(a record),ping,udp,mail(SMTP, IMAP or POP3),browser(a browser flow: scripted steps in a real browser) orheartbeat(your job pings us; we alert when the pings stop).One of
httptcpdnspingudpmailbrowserheartbeatkindstringOne of
webapiurlstringup to 2000 characters
pinnedbooleanKept near the top of the Overview.expiryAlertsbooleandescriptionstring · nullableup to 2000 characters
enabledbooleanFalse to create it paused. On update, prefer /pause and /resume.checkIntervalintegerMinutes between checks, 1 to 10080 (15 by default). Your plan sets the floor (Starter 10, others 1); browser flows run at most every 5.1 to 10080
alertAfterMinutesintegerMinutes it may stay down before an incident opens, 0 to 30 (0 by default).0 to 30
categoryIdstring · nullablestatusPageIdstring · nullableThe status page it shows on. Left out or null, it is on no page: a new monitor is never published by itself.escalationPolicyIdstring · nullablehttpMethodstringOne of
GETHEADPOSTPUTPATCHDELETErequestHeadersarray of objects · nullableup to 20 items
Show 2 child fieldsHide 2 child fields
namestringrequiredup to 100 characters
valuestringrequiredup to 2000 characters
requestBodystring · nullableup to 10000 characters
keywordstring · nullableText the response must contain (or must not).up to 500 characters
keywordModestringOne of
containsabsentjsonPathstring · nullableA dot path into a JSON response, likestatusorchecks.db.up to 200 characters
jsonExpectedstring · nullableup to 500 characters
expectedStatusCodesstring · nullableup to 200 characters
maxLatencyMsinteger · nullable50 to 60000
dnsRecordTypestringOne of
AAAAACNAMEMXTXTdnsExpectedstring · nullableup to 500 characters
pingMaxLossinteger · nullable0 to 99
udpPayloadstring · nullableup to 4000 characters
udpPayloadFormatstringOne of
texthexudpExpectedstring · nullableup to 500 characters
mailTlsstringOne of
nonestarttlstlsheartbeatGraceinteger0 to 1440
browserStepsarray of objectsBrowser flows: the scenario, the steps as the app’s editor saves them ({ "type": "goto", "url": "https://…" },click,fill,expect_text…). The firstgotoURL becomes the monitor’s url.up to 20 items
checkSslbooleancheckDomainExpirybooleanemailAlertsbooleanalertEmailsstring · nullableup to 2000 characters
Returns
200The monitor as it is now: a monitor object.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.);interval_below_plan(The plan does not check that often.);browser_limit_reached(The plan’s browser flows are all in use.);monitor_limit_reached(The plan’s monitors are all in use.) - 404
- Not found:
not_found(No such thing in this workspace.) - 422
- Unprocessable:
validation_failed(A field is wrong;detailslists them.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"description": null,
"type": "http",
"kind": "web",
"url": "https://shop.example.com/checkout",
"enabled": true,
"pausedByPlan": false,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null,
"checkInterval": 1,
"alertAfterMinutes": 0,
"categoryId": "cmh3k2x9a0002qv08cat00001",
"category": {
"id": "cmh3k2x9a0002qv08cat00001",
"name": "Acme Ltd"
},
"statusPageId": "cmh3k2x9a0003qv08page0001",
"escalationPolicyId": null,
"pinned": false,
"httpMethod": "GET",
"requestHeaders": null,
"requestBody": null,
"keyword": "Pay now",
"keywordMode": "contains",
"jsonPath": null,
"jsonExpected": null,
"expectedStatusCodes": null,
"maxLatencyMs": null,
"dnsRecordType": "A",
"dnsExpected": null,
"pingMaxLoss": null,
"udpPayload": null,
"udpPayloadFormat": "text",
"udpExpected": null,
"mailTls": "starttls",
"heartbeatGrace": 5,
"heartbeatUrl": null,
"checkSsl": true,
"checkDomainExpiry": false,
"ssl": {
"valid": true,
"expiresAt": "2027-01-20T23:59:59.000Z"
},
"domainExpiresAt": null,
"emailAlerts": true,
"alertEmails": null,
"expiryAlerts": true,
"createdAt": "2026-10-01T08:00:00.000Z",
"updatedAt": "2026-11-09T14:12:00.000Z",
"links": {
"monitor": "https://heedery.com/admin/sites/cmh3k2x9a0001qv08abcd1234"
}
}Delete a monitor
DEL/monitors/{id}
Deletes the monitor with its incidents and history. This cannot be undone; to stop checks for a while, pause it instead.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Returns
200It is gone.
Show the response fieldsHide the response fields
idstringrequireddeletedbooleanrequiredAlways
true
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0001qv08abcd1234",
"deleted": true
}Pause a monitor
POST/monitors/{id}/pause
Stops checks and alerts until it is resumed. Pausing a paused monitor changes nothing.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Returns
200The paused monitor: a monitor object.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"description": null,
"type": "http",
"kind": "web",
"url": "https://shop.example.com/checkout",
"enabled": false,
"pausedByPlan": false,
"state": "paused",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null,
"checkInterval": 1,
"alertAfterMinutes": 0,
"categoryId": "cmh3k2x9a0002qv08cat00001",
"category": {
"id": "cmh3k2x9a0002qv08cat00001",
"name": "Acme Ltd"
},
"statusPageId": "cmh3k2x9a0003qv08page0001",
"escalationPolicyId": null,
"pinned": false,
"httpMethod": "GET",
"requestHeaders": null,
"requestBody": null,
"keyword": "Pay now",
"keywordMode": "contains",
"jsonPath": null,
"jsonExpected": null,
"expectedStatusCodes": null,
"maxLatencyMs": null,
"dnsRecordType": "A",
"dnsExpected": null,
"pingMaxLoss": null,
"udpPayload": null,
"udpPayloadFormat": "text",
"udpExpected": null,
"mailTls": "starttls",
"heartbeatGrace": 5,
"heartbeatUrl": null,
"checkSsl": true,
"checkDomainExpiry": false,
"ssl": {
"valid": true,
"expiresAt": "2027-01-20T23:59:59.000Z"
},
"domainExpiresAt": null,
"emailAlerts": true,
"alertEmails": null,
"expiryAlerts": true,
"createdAt": "2026-10-01T08:00:00.000Z",
"updatedAt": "2026-11-09T14:12:00.000Z",
"links": {
"monitor": "https://heedery.com/admin/sites/cmh3k2x9a0001qv08abcd1234"
}
}Resume a monitor
POST/monitors/{id}/resume
Starts checks again. Refused when the plan already runs as many monitors as it allows.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Returns
200The running monitor: a monitor object.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.);monitor_limit_reached(The plan’s monitors are all in use.);needs_plan(The workspace has no plan, so it runs no monitors.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"description": null,
"type": "http",
"kind": "web",
"url": "https://shop.example.com/checkout",
"enabled": true,
"pausedByPlan": false,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null,
"checkInterval": 1,
"alertAfterMinutes": 0,
"categoryId": "cmh3k2x9a0002qv08cat00001",
"category": {
"id": "cmh3k2x9a0002qv08cat00001",
"name": "Acme Ltd"
},
"statusPageId": "cmh3k2x9a0003qv08page0001",
"escalationPolicyId": null,
"pinned": false,
"httpMethod": "GET",
"requestHeaders": null,
"requestBody": null,
"keyword": "Pay now",
"keywordMode": "contains",
"jsonPath": null,
"jsonExpected": null,
"expectedStatusCodes": null,
"maxLatencyMs": null,
"dnsRecordType": "A",
"dnsExpected": null,
"pingMaxLoss": null,
"udpPayload": null,
"udpPayloadFormat": "text",
"udpExpected": null,
"mailTls": "starttls",
"heartbeatGrace": 5,
"heartbeatUrl": null,
"checkSsl": true,
"checkDomainExpiry": false,
"ssl": {
"valid": true,
"expiresAt": "2027-01-20T23:59:59.000Z"
},
"domainExpiresAt": null,
"emailAlerts": true,
"alertEmails": null,
"expiryAlerts": true,
"createdAt": "2026-10-01T08:00:00.000Z",
"updatedAt": "2026-11-09T14:12:00.000Z",
"links": {
"monitor": "https://heedery.com/admin/sites/cmh3k2x9a0001qv08abcd1234"
}
}Uptime and response times
GET/monitors/{id}/metrics
Per UTC day between from and to (30 days by default, at most 90, within your plan’s history): uptime, downtime, incidents, checks, average and 95th percentile response time, and the same for the whole range. Uptime counts incident time, as the status page does.
Needs: any token (read scope), on the Pro plan or above.
Path parameters
idstringrequiredThe record id.
Query parameters
fromstringmatches ^\d{4}-\d{2}-\d{2}(T.*)?$
tostringmatches ^\d{4}-\d{2}-\d{2}(T.*)?$
Returns
200The figures.
Show the response fieldsHide the response fields
monitorIdstringrequiredfromstringrequiredFirst UTC day, inclusive.tostringrequiredLast UTC day, inclusive.summaryobjectrequiredShow 6 child fieldsHide 6 child fields
uptimePercentnumber · nullablerequiredAverage of the monitored days, as the status page counts it; null when no day was monitored.downtimeMinutesintegerrequiredincidentsintegerrequiredIncidents that overlapped the range.checksintegerrequiredavgResponseMsinteger · nullablerequiredp95ResponseMsinteger · nullablerequired
daysarray of objectsrequiredOne entry per day, oldest first.Show 9 child fieldsHide 9 child fields
datestringrequiredThe UTC day.monitoredbooleanrequiredChecks ran that day (false before the monitor existed or while paused).uptimePercentnumber · nullablerequiredShare of the day it was up, from incident time; null when not monitored.downtimeMinutesintegerrequiredincidentsintegerrequiredIncidents that overlapped the day.checksintegerrequiredfailedChecksintegerrequiredavgResponseMsinteger · nullablerequiredp95ResponseMsinteger · nullablerequired95% of the day’s successful checks answered at or under this.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"monitorId": "cmh3k2x9a0001qv08abcd1234",
"from": "2026-11-08",
"to": "2026-11-09",
"summary": {
"uptimePercent": 99.931,
"downtimeMinutes": 2,
"incidents": 1,
"checks": 2880,
"avgResponseMs": 212,
"p95ResponseMs": 480
},
"days": [
{
"date": "2026-11-08",
"monitored": true,
"uptimePercent": 100,
"downtimeMinutes": 0,
"incidents": 0,
"checks": 1440,
"failedChecks": 0,
"avgResponseMs": 205,
"p95ResponseMs": 460
},
{
"date": "2026-11-09",
"monitored": true,
"uptimePercent": 99.86,
"downtimeMinutes": 2,
"incidents": 1,
"checks": 1440,
"failedChecks": 3,
"avgResponseMs": 219,
"p95ResponseMs": 500
}
]
}The incident object
Attributes
idstringrequiredThe incident.statusstringrequiredOne of
openresolvedmonitorIdstringrequiredmonitorobjectrequiredShow 3 child fieldsHide 3 child fields
idstringrequirednamestringrequiredurlstringrequired
startedAtstring (ISO 8601)requiredThe first failed check.endedAtstring (ISO 8601) · nullablerequiredWhen it was resolved; null while open.durationSecondsintegerrequiredSo far, while open.errorstring · nullablerequiredWhat the check that opened it saw.acknowledgedAtstring (ISO 8601) · nullablerequiredWhen someone took it.acknowledgedBystring · nullablerequiredA name, an address, "Slack · #ops", or a token.resolvedManuallybooleanrequiredClosed by a person rather than by the checks.endReasonstring · nullablerequiredWhy it ended without the monitor coming back: paused (someone paused the monitor) or plan (billing paused it). Null when the checks saw it recover or a person resolved it. No recovery alert goes out for a paused end; status page subscribers who were emailed about the outage get a short “monitoring paused” email instead.One of
pausedplan
{
"id": "cmh3k2x9a0001qv08abcd1234",
"status": "open",
"monitorId": "string",
"monitor": {
"id": "string",
"name": "string",
"url": "string"
},
"startedAt": "2026-11-10T09:30:00.000Z",
"endedAt": "2026-11-10T09:30:00.000Z",
"durationSeconds": 0,
"error": "string",
"acknowledgedAt": "2026-11-10T09:30:00.000Z",
"acknowledgedBy": "string",
"resolvedManually": true,
"endReason": "paused"
}List incidents
GET/incidents
Incidents across the workspace, newest first. Filter by status, monitor and when they started.
Needs: any token (read scope), on the Pro plan or above.
Query parameters
statusstringOne of
openresolvedmonitorstringup to 100 characters
fromstringtostringlimitintegerHow many items to return, 1 to 100.Default
501 to 100cursorstringThenextCursorof the previous page; leave out for the first page. Opaque: do not build or parse it.
Returns
200A page of incidents.
Show the response fieldsHide the response fields
dataarray of objectsrequiredShow 12 child fieldsHide 12 child fields
idstringrequiredThe incident.statusstringrequiredOne of
openresolvedmonitorIdstringrequiredmonitorobjectrequiredShow 3 child fieldsHide 3 child fields
idstringrequirednamestringrequiredurlstringrequired
startedAtstring (ISO 8601)requiredThe first failed check.endedAtstring (ISO 8601) · nullablerequiredWhen it was resolved; null while open.durationSecondsintegerrequiredSo far, while open.errorstring · nullablerequiredWhat the check that opened it saw.acknowledgedAtstring (ISO 8601) · nullablerequiredWhen someone took it.acknowledgedBystring · nullablerequiredA name, an address, "Slack · #ops", or a token.resolvedManuallybooleanrequiredClosed by a person rather than by the checks.endReasonstring · nullablerequiredWhy it ended without the monitor coming back: paused (someone paused the monitor) or plan (billing paused it). Null when the checks saw it recover or a person resolved it. No recovery alert goes out for a paused end; status page subscribers who were emailed about the outage get a short “monitoring paused” email instead.One of
pausedplan
nextCursorstring · nullablerequiredPass ascursorto get the next page; null on the last page.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"data": [
{
"id": "cmh3k2x9a0009qv08inc00001",
"status": "open",
"monitorId": "cmh3k2x9a0001qv08abcd1234",
"monitor": {
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"url": "https://shop.example.com/checkout"
},
"startedAt": "2026-11-10T09:12:00.000Z",
"endedAt": null,
"durationSeconds": 1080,
"error": "HTTP 503",
"acknowledgedAt": null,
"acknowledgedBy": null,
"resolvedManually": false,
"endReason": null
}
],
"nextCursor": null
}Get an incident
GET/incidents/{id}
One incident with its timeline (first failure, alerts, escalation, acknowledgement, comments, resolution), what the failing check saw, and a deploy that shortly preceded it.
Needs: any token (read scope), on the Pro plan or above.
Path parameters
idstringrequiredThe record id.
Returns
200The incident.
Show the response fieldsHide the response fields
idstringrequiredThe incident.statusstringrequiredOne of
openresolvedmonitorIdstringrequiredmonitorobjectrequiredShow 3 child fieldsHide 3 child fields
idstringrequirednamestringrequiredurlstringrequired
startedAtstring (ISO 8601)requiredThe first failed check.endedAtstring (ISO 8601) · nullablerequiredWhen it was resolved; null while open.durationSecondsintegerrequiredSo far, while open.errorstring · nullablerequiredWhat the check that opened it saw.acknowledgedAtstring (ISO 8601) · nullablerequiredWhen someone took it.acknowledgedBystring · nullablerequiredA name, an address, "Slack · #ops", or a token.resolvedManuallybooleanrequiredClosed by a person rather than by the checks.endReasonstring · nullablerequiredWhy it ended without the monitor coming back: paused (someone paused the monitor) or plan (billing paused it). Null when the checks saw it recover or a person resolved it. No recovery alert goes out for a paused end; status page subscribers who were emailed about the outage get a short “monitoring paused” email instead.One of
pausedplanopenedAtstring (ISO 8601)requiredWhen the incident opened (after the confirming checks and any alert delay).failedRegionsarray of stringsrequiredCheck regions that saw the failure, the main first.evidenceobject · nullablerequiredWhat the check that opened it saw; null for incidents from before evidence was recorded.Show 11 child fieldsHide 11 child fields
capturedAtstring (ISO 8601)requiredWhen the failing check ran.categorystringrequiredWhat kind of failure: dns, connect, tls, timeout, httpstatus, keywordmissing…summarystringrequiredThe failure in one plain sentence.notesarray of stringsrequiredcheckTypestringrequiredtargetstringrequiredstatusCodeinteger · nullablerequirederrorstring · nullablerequiredtotalMsinteger · nullablerequiredphasesarray of objectsrequiredShow 4 child fieldsHide 4 child fields
keystringrequiredlabelstringrequiredmsnumberrequiredfailedbooleanrequired
screenshotUrlstring · nullablerequiredA signed link to the screenshot of the page, when one was taken (Pro and up).
deployBeforeobject · nullablerequiredA deploy reported up to 30 minutes before it began, if any.Show 4 child fieldsHide 4 child fields
idstringrequiredversionstringrequireddeployedAtstring (ISO 8601)requiredWhen it went live.minutesBeforenumberrequired
timelinearray of objectsrequiredWhat happened, oldest first.Show 4 child fieldsHide 4 child fields
atstring (ISO 8601)requiredWhen.kindstringrequiredOne of
first_failureopenednotifiedescalatedacknowledgedcommentresolvedpausedtitlestringrequireddetailstring · nullablerequired
commentsarray of objectsrequiredShow 5 child fieldsHide 5 child fields
idstringrequiredauthorstringrequiredbodystringrequiredcreatedAtstring (ISO 8601)requiredWhen it was written.editedAtstring (ISO 8601) · nullablerequiredWhen it was last changed.
- 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0009qv08inc00001",
"status": "open",
"monitorId": "cmh3k2x9a0001qv08abcd1234",
"monitor": {
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"url": "https://shop.example.com/checkout"
},
"startedAt": "2026-11-10T09:12:00.000Z",
"endedAt": null,
"durationSeconds": 1080,
"error": "HTTP 503",
"acknowledgedAt": null,
"acknowledgedBy": null,
"resolvedManually": false,
"endReason": null,
"openedAt": "2026-11-10T09:14:00.000Z",
"failedRegions": [
"eu-central",
"us-east"
],
"evidence": {
"capturedAt": "2026-11-10T09:12:00.000Z",
"category": "http_status",
"summary": "The server answered 503 Service Unavailable.",
"notes": [
"The page title was \"Maintenance\"."
],
"checkType": "http",
"target": "https://shop.example.com/checkout",
"statusCode": 503,
"error": "HTTP 503",
"totalMs": 412,
"phases": [
{
"key": "dns",
"label": "DNS",
"ms": 12,
"failed": false
},
{
"key": "connect",
"label": "Connect",
"ms": 30,
"failed": false
},
{
"key": "tls",
"label": "TLS",
"ms": 60,
"failed": false
},
{
"key": "firstByte",
"label": "First byte",
"ms": 300,
"failed": false
},
{
"key": "transfer",
"label": "Download",
"ms": 10,
"failed": false
}
],
"screenshotUrl": null
},
"deployBefore": {
"id": "cmh3k2x9a0010qv08dep00001",
"version": "v1.4.2",
"deployedAt": "2026-11-10T09:05:00.000Z",
"minutesBefore": 7
},
"timeline": [
{
"at": "2026-11-10T09:12:00.000Z",
"kind": "first_failure",
"title": "First failed check",
"detail": "HTTP 503"
},
{
"at": "2026-11-10T09:14:00.000Z",
"kind": "opened",
"title": "Incident opened",
"detail": "After 2 failed checks"
}
],
"comments": []
}Acknowledge an incident
POST/incidents/{id}/acknowledge
"We are on it": repeat alerts and escalation stop. The timeline names the token. Acknowledging one someone already took is not an error (result: "already").
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Returns
200Acknowledged.
Show the response fieldsHide the response fields
resultstringrequireddone: acknowledged now;already: someone was first (see incident.acknowledgedBy).One of
donealreadyincidentobjectrequiredShow 18 child fieldsHide 18 child fields
idstringrequiredThe incident.statusstringrequiredOne of
openresolvedmonitorIdstringrequiredmonitorobjectrequiredShow 3 child fieldsHide 3 child fields
idstringrequirednamestringrequiredurlstringrequired
startedAtstring (ISO 8601)requiredThe first failed check.endedAtstring (ISO 8601) · nullablerequiredWhen it was resolved; null while open.durationSecondsintegerrequiredSo far, while open.errorstring · nullablerequiredWhat the check that opened it saw.acknowledgedAtstring (ISO 8601) · nullablerequiredWhen someone took it.acknowledgedBystring · nullablerequiredA name, an address, "Slack · #ops", or a token.resolvedManuallybooleanrequiredClosed by a person rather than by the checks.endReasonstring · nullablerequiredWhy it ended without the monitor coming back: paused (someone paused the monitor) or plan (billing paused it). Null when the checks saw it recover or a person resolved it. No recovery alert goes out for a paused end; status page subscribers who were emailed about the outage get a short “monitoring paused” email instead.One of
pausedplanopenedAtstring (ISO 8601)requiredWhen the incident opened (after the confirming checks and any alert delay).failedRegionsarray of stringsrequiredCheck regions that saw the failure, the main first.evidenceobject · nullablerequiredWhat the check that opened it saw; null for incidents from before evidence was recorded.Show 11 child fieldsHide 11 child fields
capturedAtstring (ISO 8601)requiredWhen the failing check ran.categorystringrequiredWhat kind of failure: dns, connect, tls, timeout, httpstatus, keywordmissing…summarystringrequiredThe failure in one plain sentence.notesarray of stringsrequiredcheckTypestringrequiredtargetstringrequiredstatusCodeinteger · nullablerequirederrorstring · nullablerequiredtotalMsinteger · nullablerequiredphasesarray of objectsrequiredShow 4 child fieldsHide 4 child fields
keystringrequiredlabelstringrequiredmsnumberrequiredfailedbooleanrequired
screenshotUrlstring · nullablerequiredA signed link to the screenshot of the page, when one was taken (Pro and up).
deployBeforeobject · nullablerequiredA deploy reported up to 30 minutes before it began, if any.Show 4 child fieldsHide 4 child fields
idstringrequiredversionstringrequireddeployedAtstring (ISO 8601)requiredWhen it went live.minutesBeforenumberrequired
timelinearray of objectsrequiredWhat happened, oldest first.Show 4 child fieldsHide 4 child fields
atstring (ISO 8601)requiredWhen.kindstringrequiredOne of
first_failureopenednotifiedescalatedacknowledgedcommentresolvedpausedtitlestringrequireddetailstring · nullablerequired
commentsarray of objectsrequiredShow 5 child fieldsHide 5 child fields
idstringrequiredauthorstringrequiredbodystringrequiredcreatedAtstring (ISO 8601)requiredWhen it was written.editedAtstring (ISO 8601) · nullablerequiredWhen it was last changed.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 404
- Not found:
not_found(No such thing in this workspace.) - 409
- Conflict:
incident_resolved(The incident is already resolved.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"result": "done",
"incident": {
"id": "cmh3k2x9a0009qv08inc00001",
"status": "open",
"monitorId": "cmh3k2x9a0001qv08abcd1234",
"monitor": {
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout",
"url": "https://shop.example.com/checkout"
},
"startedAt": "2026-11-10T09:12:00.000Z",
"endedAt": null,
"durationSeconds": 1080,
"error": "HTTP 503",
"acknowledgedAt": "2026-11-10T09:20:00.000Z",
"acknowledgedBy": "CRM (API)",
"resolvedManually": false,
"endReason": null,
"openedAt": "2026-11-10T09:14:00.000Z",
"failedRegions": [
"eu-central",
"us-east"
],
"evidence": {
"capturedAt": "2026-11-10T09:12:00.000Z",
"category": "http_status",
"summary": "The server answered 503 Service Unavailable.",
"notes": [
"The page title was \"Maintenance\"."
],
"checkType": "http",
"target": "https://shop.example.com/checkout",
"statusCode": 503,
"error": "HTTP 503",
"totalMs": 412,
"phases": [
{
"key": "dns",
"label": "DNS",
"ms": 12,
"failed": false
},
{
"key": "connect",
"label": "Connect",
"ms": 30,
"failed": false
},
{
"key": "tls",
"label": "TLS",
"ms": 60,
"failed": false
},
{
"key": "firstByte",
"label": "First byte",
"ms": 300,
"failed": false
},
{
"key": "transfer",
"label": "Download",
"ms": 10,
"failed": false
}
],
"screenshotUrl": null
},
"deployBefore": {
"id": "cmh3k2x9a0010qv08dep00001",
"version": "v1.4.2",
"deployedAt": "2026-11-10T09:05:00.000Z",
"minutesBefore": 7
},
"timeline": [
{
"at": "2026-11-10T09:12:00.000Z",
"kind": "first_failure",
"title": "First failed check",
"detail": "HTTP 503"
},
{
"at": "2026-11-10T09:14:00.000Z",
"kind": "opened",
"title": "Incident opened",
"detail": "After 2 failed checks"
}
],
"comments": []
}
}Comment on an incident
POST/incidents/{id}/comments
Adds an internal note to the incident’s timeline, signed with the token’s name. Status page subscribers never see it.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Body
JSONbodystringrequiredThe note, up to 2000 characters. Internal: it is never shown on a status page.1 to 2000 characters
Returns
201The incident with the new comment.
Show the response fieldsHide the response fields
idstringrequiredThe incident.statusstringrequiredOne of
openresolvedmonitorIdstringrequiredmonitorobjectrequiredShow 3 child fieldsHide 3 child fields
idstringrequirednamestringrequiredurlstringrequired
startedAtstring (ISO 8601)requiredThe first failed check.endedAtstring (ISO 8601) · nullablerequiredWhen it was resolved; null while open.durationSecondsintegerrequiredSo far, while open.errorstring · nullablerequiredWhat the check that opened it saw.acknowledgedAtstring (ISO 8601) · nullablerequiredWhen someone took it.acknowledgedBystring · nullablerequiredA name, an address, "Slack · #ops", or a token.resolvedManuallybooleanrequiredClosed by a person rather than by the checks.endReasonstring · nullablerequiredWhy it ended without the monitor coming back: paused (someone paused the monitor) or plan (billing paused it). Null when the checks saw it recover or a person resolved it. No recovery alert goes out for a paused end; status page subscribers who were emailed about the outage get a short “monitoring paused” email instead.One of
pausedplanopenedAtstring (ISO 8601)requiredWhen the incident opened (after the confirming checks and any alert delay).failedRegionsarray of stringsrequiredCheck regions that saw the failure, the main first.evidenceobject · nullablerequiredWhat the check that opened it saw; null for incidents from before evidence was recorded.Show 11 child fieldsHide 11 child fields
capturedAtstring (ISO 8601)requiredWhen the failing check ran.categorystringrequiredWhat kind of failure: dns, connect, tls, timeout, httpstatus, keywordmissing…summarystringrequiredThe failure in one plain sentence.notesarray of stringsrequiredcheckTypestringrequiredtargetstringrequiredstatusCodeinteger · nullablerequirederrorstring · nullablerequiredtotalMsinteger · nullablerequiredphasesarray of objectsrequiredShow 4 child fieldsHide 4 child fields
keystringrequiredlabelstringrequiredmsnumberrequiredfailedbooleanrequired
screenshotUrlstring · nullablerequiredA signed link to the screenshot of the page, when one was taken (Pro and up).
deployBeforeobject · nullablerequiredA deploy reported up to 30 minutes before it began, if any.Show 4 child fieldsHide 4 child fields
idstringrequiredversionstringrequireddeployedAtstring (ISO 8601)requiredWhen it went live.minutesBeforenumberrequired
timelinearray of objectsrequiredWhat happened, oldest first.Show 4 child fieldsHide 4 child fields
atstring (ISO 8601)requiredWhen.kindstringrequiredOne of
first_failureopenednotifiedescalatedacknowledgedcommentresolvedpausedtitlestringrequireddetailstring · nullablerequired
commentsarray of objectsrequiredShow 5 child fieldsHide 5 child fields
idstringrequiredauthorstringrequiredbodystringrequiredcreatedAtstring (ISO 8601)requiredWhen it was written.editedAtstring (ISO 8601) · nullablerequiredWhen it was last changed.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 404
- Not found:
not_found(No such thing in this workspace.) - 409
- Conflict:
idempotency_in_progress(A request with this Idempotency-Key is still running.) - 422
- Unprocessable:
validation_failed(A field is wrong;detailslists them.);idempotency_key_reused(The Idempotency-Key was used with a different request.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0001qv08abcd1234",
"status": "open",
"monitorId": "string",
"monitor": {
"id": "string",
"name": "string",
"url": "string"
},
"startedAt": "2026-11-10T09:30:00.000Z",
"endedAt": "2026-11-10T09:30:00.000Z",
"durationSeconds": 0,
"error": "string",
"acknowledgedAt": "2026-11-10T09:30:00.000Z",
"acknowledgedBy": "string",
"resolvedManually": true,
"endReason": "paused",
"openedAt": "2026-11-10T09:30:00.000Z",
"failedRegions": [
"string"
],
"evidence": {
"capturedAt": "2026-11-10T09:30:00.000Z",
"category": "string",
"summary": "string",
"notes": [
"string"
],
"checkType": "string",
"target": "string",
"statusCode": 0,
"error": "string",
"totalMs": 0,
"phases": [
{
"key": "string",
"label": "string",
"ms": 0,
"failed": true
}
],
"screenshotUrl": "string"
},
"deployBefore": {
"id": "string",
"version": "string",
"deployedAt": "2026-11-10T09:30:00.000Z",
"minutesBefore": 0
},
"timeline": [
{
"at": "2026-11-10T09:30:00.000Z",
"kind": "first_failure",
"title": "string",
"detail": "string"
}
],
"comments": [
{
"id": "string",
"author": "string",
"body": "string",
"createdAt": "2026-11-10T09:30:00.000Z",
"editedAt": "2026-11-10T09:30:00.000Z"
}
]
}List maintenance windows
GET/maintenance
Maintenance windows, latest start first. While one runs, its monitors’ alerts are held and the status page says so.
Needs: any token (read scope), on the Pro plan or above.
Query parameters
phasestringOne of
upcomingactiveendedcancelledlimitintegerHow many items to return, 1 to 100.Default
501 to 100cursorstringThenextCursorof the previous page; leave out for the first page. Opaque: do not build or parse it.
Returns
200A page of windows.
Show the response fieldsHide the response fields
dataarray of objectsrequiredShow 11 child fieldsHide 11 child fields
idstringrequiredThe window.titlestringrequiredmessagestring · nullablerequiredstartsAtstring (ISO 8601)requiredWhen it starts.endsAtstring (ISO 8601)requiredWhen it ends.phasestringrequiredOne of
upcomingactiveendedcancelledcancelledAtstring (ISO 8601) · nullablerequiredWhen it was called off before it began.notifiedAtstring (ISO 8601) · nullablerequiredWhen status page subscribers were told about it.createdAtstring (ISO 8601)requiredWhen it was scheduled.createdBystring · nullablerequiredmonitorsarray of objectsrequiredShow 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
nextCursorstring · nullablerequiredPass ascursorto get the next page; null on the last page.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"data": [
{
"id": "cmh3k2x9a0011qv08mnt00001",
"title": "Database upgrade",
"message": "Checkout may be slow for a few minutes.",
"startsAt": "2026-11-12T22:00:00.000Z",
"endsAt": "2026-11-12T23:00:00.000Z",
"phase": "upcoming",
"cancelledAt": null,
"notifiedAt": "2026-11-10T09:31:00.000Z",
"createdAt": "2026-11-10T09:30:00.000Z",
"createdBy": null,
"monitors": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout"
}
]
}
],
"nextCursor": null
}Schedule maintenance
POST/maintenance
Schedules a window, or starts one now when startsAt is left out. Subscribers of the affected status pages are told by email.
Needs: a token with the write scope, on the Team plan or above.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Body
JSONtitlestringrequired1 to 120 characters
messagestring · nullableShown on the status page and in the subscriber email.up to 2000 characters
endsAtstring (ISO 8601)requiredWhen it ends; at most 14 days after the start.monitorIdsarray of stringsrequiredThe monitors it covers. Their alerts are held while it runs.1 to 1000 items
startsAtstring (ISO 8601)When it starts; now by default.
Returns
201The window.
Show the response fieldsHide the response fields
idstringrequiredThe window.titlestringrequiredmessagestring · nullablerequiredstartsAtstring (ISO 8601)requiredWhen it starts.endsAtstring (ISO 8601)requiredWhen it ends.phasestringrequiredOne of
upcomingactiveendedcancelledcancelledAtstring (ISO 8601) · nullablerequiredWhen it was called off before it began.notifiedAtstring (ISO 8601) · nullablerequiredWhen status page subscribers were told about it.createdAtstring (ISO 8601)requiredWhen it was scheduled.createdBystring · nullablerequiredmonitorsarray of objectsrequiredShow 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 409
- Conflict:
idempotency_in_progress(A request with this Idempotency-Key is still running.) - 422
- Unprocessable:
validation_failed(A field is wrong;detailslists them.);idempotency_key_reused(The Idempotency-Key was used with a different request.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0011qv08mnt00001",
"title": "Database upgrade",
"message": "Checkout may be slow for a few minutes.",
"startsAt": "2026-11-12T22:00:00.000Z",
"endsAt": "2026-11-12T23:00:00.000Z",
"phase": "upcoming",
"cancelledAt": null,
"notifiedAt": "2026-11-10T09:31:00.000Z",
"createdAt": "2026-11-10T09:30:00.000Z",
"createdBy": null,
"monitors": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout"
}
]
}Get a maintenance window
GET/maintenance/{id}
One window and the monitors it covers.
Needs: any token (read scope), on the Pro plan or above.
Path parameters
idstringrequiredThe record id.
Returns
200The window.
Show the response fieldsHide the response fields
idstringrequiredThe window.titlestringrequiredmessagestring · nullablerequiredstartsAtstring (ISO 8601)requiredWhen it starts.endsAtstring (ISO 8601)requiredWhen it ends.phasestringrequiredOne of
upcomingactiveendedcancelledcancelledAtstring (ISO 8601) · nullablerequiredWhen it was called off before it began.notifiedAtstring (ISO 8601) · nullablerequiredWhen status page subscribers were told about it.createdAtstring (ISO 8601)requiredWhen it was scheduled.createdBystring · nullablerequiredmonitorsarray of objectsrequiredShow 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
- 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0011qv08mnt00001",
"title": "Database upgrade",
"message": "Checkout may be slow for a few minutes.",
"startsAt": "2026-11-12T22:00:00.000Z",
"endsAt": "2026-11-12T23:00:00.000Z",
"phase": "upcoming",
"cancelledAt": null,
"notifiedAt": "2026-11-10T09:31:00.000Z",
"createdAt": "2026-11-10T09:30:00.000Z",
"createdBy": null,
"monitors": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout"
}
]
}Update a maintenance window
PATCH/maintenance/{id}
Changes a window that has not ended (a running one can be extended). Subscribers who were told about it hear about a new time or new monitors once.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Body
JSONtitlestring1 to 120 characters
messagestring · nullableShown on the status page and in the subscriber email.up to 2000 characters
startsAtstring (ISO 8601)endsAtstring (ISO 8601)When it ends; at most 14 days after the start.monitorIdsarray of stringsThe monitors it covers. Their alerts are held while it runs.1 to 1000 items
Returns
200The window as it is now.
Show the response fieldsHide the response fields
idstringrequiredThe window.titlestringrequiredmessagestring · nullablerequiredstartsAtstring (ISO 8601)requiredWhen it starts.endsAtstring (ISO 8601)requiredWhen it ends.phasestringrequiredOne of
upcomingactiveendedcancelledcancelledAtstring (ISO 8601) · nullablerequiredWhen it was called off before it began.notifiedAtstring (ISO 8601) · nullablerequiredWhen status page subscribers were told about it.createdAtstring (ISO 8601)requiredWhen it was scheduled.createdBystring · nullablerequiredmonitorsarray of objectsrequiredShow 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 404
- Not found:
not_found(No such thing in this workspace.) - 409
- Conflict:
window_closed(The window has ended or was cancelled.) - 422
- Unprocessable:
validation_failed(A field is wrong;detailslists them.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0011qv08mnt00001",
"title": "Database upgrade",
"message": "Checkout may be slow for a few minutes.",
"startsAt": "2026-11-12T22:00:00.000Z",
"endsAt": "2026-11-12T23:00:00.000Z",
"phase": "upcoming",
"cancelledAt": null,
"notifiedAt": "2026-11-10T09:31:00.000Z",
"createdAt": "2026-11-10T09:30:00.000Z",
"createdBy": null,
"monitors": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout"
}
]
}Delete a maintenance window
DEL/maintenance/{id}
Removes a window in any phase. One that is running ends now and one that has not started is called off first; subscribers who were told hear that before it goes.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Returns
200It is gone.
Show the response fieldsHide the response fields
idstringrequireddeletedbooleanrequiredAlways
true
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 404
- Not found:
not_found(No such thing in this workspace.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0011qv08mnt00001",
"deleted": true
}End maintenance now
POST/maintenance/{id}/end
Ends a running window early: alerts resume, subscribers who were told hear it is over.
Needs: a token with the write scope, on the Team plan or above.
Path parameters
idstringrequiredThe record id.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Returns
200The ended window.
Show the response fieldsHide the response fields
idstringrequiredThe window.titlestringrequiredmessagestring · nullablerequiredstartsAtstring (ISO 8601)requiredWhen it starts.endsAtstring (ISO 8601)requiredWhen it ends.phasestringrequiredOne of
upcomingactiveendedcancelledcancelledAtstring (ISO 8601) · nullablerequiredWhen it was called off before it began.notifiedAtstring (ISO 8601) · nullablerequiredWhen status page subscribers were told about it.createdAtstring (ISO 8601)requiredWhen it was scheduled.createdBystring · nullablerequiredmonitorsarray of objectsrequiredShow 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 404
- Not found:
not_found(No such thing in this workspace.) - 409
- Conflict:
not_running(The window is not running.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0011qv08mnt00001",
"title": "Database upgrade",
"message": "Checkout may be slow for a few minutes.",
"startsAt": "2026-11-12T22:00:00.000Z",
"endsAt": "2026-11-12T23:00:00.000Z",
"phase": "ended",
"cancelledAt": null,
"notifiedAt": "2026-11-10T09:31:00.000Z",
"createdAt": "2026-11-10T09:30:00.000Z",
"createdBy": null,
"monitors": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop checkout"
}
]
}The deploy object
Attributes
idstringrequiredThe deploy.versionstringrequiredcommitstring · nullablerequiredenvironmentstring · nullablerequireddescriptionstring · nullablerequiredurlstring · nullablerequiredsourcestring · nullablerequiredThe token that reported it.deployedAtstring (ISO 8601)requiredWhen it went live.createdAtstring (ISO 8601)requiredWhen it was reported.monitorIdsarray of stringsrequiredThe monitors it is about; empty = all of them.
{
"id": "cmh3k2x9a0001qv08abcd1234",
"version": "string",
"commit": "string",
"environment": "string",
"description": "string",
"url": "string",
"source": "string",
"deployedAt": "2026-11-10T09:30:00.000Z",
"createdAt": "2026-11-10T09:30:00.000Z",
"monitorIds": [
"string"
]
}List deploys
GET/deploys
Deploys reported by CI or the API, newest first: the markers on the response-time charts. Pro and above.
Needs: any token (read scope), on the Pro plan or above.
Query parameters
monitorstringup to 100 characters
fromstringtostringlimitintegerHow many items to return, 1 to 100.Default
501 to 100cursorstringThenextCursorof the previous page; leave out for the first page. Opaque: do not build or parse it.
Returns
200A page of deploys.
Show the response fieldsHide the response fields
dataarray of objectsrequiredShow 10 child fieldsHide 10 child fields
idstringrequiredThe deploy.versionstringrequiredcommitstring · nullablerequiredenvironmentstring · nullablerequireddescriptionstring · nullablerequiredurlstring · nullablerequiredsourcestring · nullablerequiredThe token that reported it.deployedAtstring (ISO 8601)requiredWhen it went live.createdAtstring (ISO 8601)requiredWhen it was reported.monitorIdsarray of stringsrequiredThe monitors it is about; empty = all of them.
nextCursorstring · nullablerequiredPass ascursorto get the next page; null on the last page.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"data": [
{
"id": "cmh3k2x9a0010qv08dep00001",
"version": "v1.4.2",
"commit": "9f2c1ab",
"environment": "production",
"description": null,
"url": null,
"source": "GitHub Actions",
"deployedAt": "2026-11-10T09:05:00.000Z",
"createdAt": "2026-11-10T09:05:02.000Z",
"monitorIds": [
"cmh3k2x9a0001qv08abcd1234"
]
}
],
"nextCursor": null
}Report a deploy
POST/deploys
Marks a release on the charts; an incident that starts within 30 minutes names it. The same as the CI webhook (POST /api/deploys with a deploy token), with an API token instead.
Needs: a token with the write scope, on the Team plan or above.
Headers
Idempotency-KeystringAny unique string (a UUID). A retry with the same key and body within 24 hours gets the first answer instead of doing it twice.up to 255 characters
Body
JSONversionstringrequiredWhat shipped: a tag, release name or ref.1 to 100 characters
commitstring · nullableThe commit sha (4 to 64 hex characters).up to 64 characters
environmentstring · nullableup to 40 characters
descriptionstring · nullableup to 500 characters
urlstring · nullableA link to the release, the pipeline run or the diff.up to 2000 characters
monitorsarray of strings · nullableThe monitors it is about, by id, host or URL; leave out for all of them.up to 100 items
deployedAtstring or numberWhen it went live: an ISO time or a Unix timestamp; now by default, at most 30 days back.
Returns
201The deploy: a deploy object.
- 400
- Bad request:
invalid_request(A query parameter, the cursor or the JSON is malformed.) - 401
- Unauthorized:
unauthorized(No token, or an unknown one.) - 403
- Forbidden:
plan_required(The plan does not include this: the API needs Pro, writes need Team.);scope_required(The token only reads; this needs the write scope.) - 409
- Conflict:
idempotency_in_progress(A request with this Idempotency-Key is still running.) - 422
- Unprocessable:
validation_failed(A field is wrong;detailslists them.);idempotency_key_reused(The Idempotency-Key was used with a different request.) - 429
- Too many requests:
rate_limited(Too many requests; see Retry-After.) - 500
- Server error:
internal_error(Something broke on our side.)
{
"id": "cmh3k2x9a0010qv08dep00001",
"version": "v1.4.2",
"commit": "9f2c1ab",
"environment": "production",
"description": null,
"url": null,
"source": "GitHub Actions",
"deployedAt": "2026-11-10T09:05:00.000Z",
"createdAt": "2026-11-10T09:05:02.000Z",
"monitorIds": [
"cmh3k2x9a0001qv08abcd1234"
]
}Status of every site
GET/status
Every monitor in the state the Overview shows, with the last check and the open incident. ?ids=a,b narrows it (at most 200). The first route of the API, kept as it is; for filters and pages use /monitors.
Needs: any token (read scope), on the Pro plan or above.
Query parameters
idsstring
Returns
200The workspace and its sites.
Show the response fieldsHide the response fields
workspaceobjectrequiredShow 2 child fieldsHide 2 child fields
idstringrequirednamestringrequired
generatedAtstring (ISO 8601)requiredsitesarray of objectsrequiredShow 11 child fieldsHide 11 child fields
idstringrequirednamestringrequiredurlstringrequiredkindstringrequiredenabledbooleanrequiredstatestringrequiredOne of
updownpausedunknownmaintenanceblockedcheckedAtstring (ISO 8601) · nullablerequiredlatencyMsinteger · nullablerequiredstatusCodeinteger · nullablerequirederrorstring · nullablerequiredincidentobject · nullablerequiredShow 3 child fieldsHide 3 child fields
idstringrequiredstartedAtstring (ISO 8601)requirederrorstring · nullablerequired
- 400
- Bad request. The original error shape:
{ "error": "text" }. - 401
- Unauthorized. The original error shape:
{ "error": "text" }. - 403
- Forbidden. The original error shape:
{ "error": "text" }. - 429
- Too many requests. The original error shape:
{ "error": "text" }.
{
"workspace": {
"id": "cmh3k2x9a0000qv08wksp0001",
"name": "Acme"
},
"generatedAt": "2026-11-10T09:30:00.000Z",
"sites": [
{
"id": "cmh3k2x9a0001qv08abcd1234",
"name": "Shop",
"url": "https://shop.example.com/",
"kind": "web",
"enabled": true,
"state": "up",
"checkedAt": "2026-11-10T09:29:12.000Z",
"latencyMs": 182,
"statusCode": 200,
"error": null,
"incident": null
}
]
}One site with its history (deprecated)
GET/sites/{id}
Uptime over 30 and 90 days, the last 30 days, the 24-hour response time, certificate and domain expiry, recent incidents, PageSpeed and links. Kept for existing integrations; use /monitors/{id} and /monitors/{id}/metrics.
Needs: any token (read scope), on the Pro plan or above.
Path parameters
idstringrequiredThe record id.
Returns
200The site.
Show the response fieldsHide the response fields
generatedAtstring (ISO 8601)requiredsiteobjectrequiredShow 11 child fieldsHide 11 child fields
idstringrequirednamestringrequiredurlstringrequiredkindstringrequiredenabledbooleanrequiredstatestringrequiredOne of
updownpausedunknownmaintenanceblockedcheckedAtstring (ISO 8601) · nullablerequiredlatencyMsinteger · nullablerequiredstatusCodeinteger · nullablerequirederrorstring · nullablerequiredincidentobject · nullablerequiredShow 3 child fieldsHide 3 child fields
idstringrequiredstartedAtstring (ISO 8601)requirederrorstring · nullablerequired
uptimeobjectrequiredShow 2 child fieldsHide 2 child fields
days30number · nullablerequireddays90number · nullablerequired
daysarray of objectsrequiredShow 4 child fieldsHide 4 child fields
datestringrequiredmonitoredbooleanrequireddowntimeMinutesintegerrequiredincidentsintegerrequired
latency24hobjectrequiredShow 2 child fieldsHide 2 child fields
hourlyarray of numbersrequiredavgMsnumber · nullablerequired
sslobject · nullablerequiredShow 2 child fieldsHide 2 child fields
validboolean · nullablerequiredexpiresAtstring (ISO 8601) · nullablerequired
domainExpiresAtstring (ISO 8601) · nullablerequiredincidentsarray of objectsrequiredShow 4 child fieldsHide 4 child fields
idstringrequiredstartedAtstring (ISO 8601)requiredendedAtstring (ISO 8601) · nullablerequirederrorstring · nullablerequired
pagespeedobject · nullablerequiredThe latest PageSpeed runs: phone at the top level, desktop underdesktop; null without runs.Show 12 child fieldsHide 12 child fields
checkedAtstring (ISO 8601)requirederrorstring · nullablerequiredurlstringrequiredlatestobject · nullablerequiredShow 9 child fieldsHide 9 child fields
atstring (ISO 8601)requiredscorenumber · nullablerequiredaccessibilitynumber · nullablerequiredbestPracticesnumber · nullablerequiredseonumber · nullablerequiredlcpMsnumber · nullablerequiredclsnumber · nullablerequiredinpMsnumber · nullablerequiredsourcestringrequiredOne of
fieldlab
historyarray of objectsrequiredShow 2 child fieldsHide 2 child fields
atstring (ISO 8601)requiredscorenumber · nullablerequired
fieldobject · nullablerequiredShow 4 child fieldsHide 4 child fields
overallstring · nullablerequiredOne of
fastaverageslowlcpobject · nullablerequiredShow 2 child fieldsHide 2 child fields
p75numberrequiredgoodnumberrequired
inpobject · nullablerequiredShow 2 child fieldsHide 2 child fields
p75numberrequiredgoodnumberrequired
clsobject · nullablerequiredShow 2 child fieldsHide 2 child fields
p75numberrequiredgoodnumberrequired
labobject · nullablerequiredShow 5 child fieldsHide 5 child fields
fcpMsnumber · nullablerequiredlcpMsnumber · nullablerequiredtbtMsnumber · nullablerequiredclsnumber · nullablerequiredspeedIndexMsnumber · nullablerequired
auditsarray of objectsrequiredShow 3 child fieldsHide 3 child fields
titlestringrequireddisplaystring · nullablerequiredsavingsMsnumber · nullablerequired
issuesobjectrequiredShow 3 child fieldsHide 3 child fields
accessibilityintegerrequiredbestPracticesintegerrequiredseointegerrequired
reportUrlstring · nullablerequiredThe full Lighthouse report of the run inlatest(the official HTML report, nothing is run again), as a signed link anyone can open without an account. Add?download=1to save it,?format=jsonfor the JSON. It works for 30 days after the run unless the site is deleted; take it from here when a person opens the site rather than storing it. Null when that run has no stored report.reportedAtstring (ISO 8601) · nullablerequiredWhen the run behindreportUrlwas made.desktopobject · nullablerequiredShow 8 child fieldsHide 8 child fields
latestobjectrequiredShow 9 child fieldsHide 9 child fields
atstring (ISO 8601)requiredscorenumber · nullablerequiredaccessibilitynumber · nullablerequiredbestPracticesnumber · nullablerequiredseonumber · nullablerequiredlcpMsnumber · nullablerequiredclsnumber · nullablerequiredinpMsnumber · nullablerequiredsourcestringrequiredOne of
fieldlab
historyarray of objectsrequiredShow 2 child fieldsHide 2 child fields
atstring (ISO 8601)requiredscorenumber · nullablerequired
fieldobject · nullablerequiredShow 4 child fieldsHide 4 child fields
overallstring · nullablerequiredOne of
fastaverageslowlcpobject · nullablerequiredShow 2 child fieldsHide 2 child fields
p75numberrequiredgoodnumberrequired
inpobject · nullablerequiredShow 2 child fieldsHide 2 child fields
p75numberrequiredgoodnumberrequired
clsobject · nullablerequiredShow 2 child fieldsHide 2 child fields
p75numberrequiredgoodnumberrequired
labobject · nullablerequiredShow 5 child fieldsHide 5 child fields
fcpMsnumber · nullablerequiredlcpMsnumber · nullablerequiredtbtMsnumber · nullablerequiredclsnumber · nullablerequiredspeedIndexMsnumber · nullablerequired
auditsarray of objectsrequiredShow 3 child fieldsHide 3 child fields
titlestringrequireddisplaystring · nullablerequiredsavingsMsnumber · nullablerequired
issuesobjectrequiredShow 3 child fieldsHide 3 child fields
accessibilityintegerrequiredbestPracticesintegerrequiredseointegerrequired
reportUrlstring · nullablerequiredThe full Lighthouse report of the run inlatest(the official HTML report, nothing is run again), as a signed link anyone can open without an account. Add?download=1to save it,?format=jsonfor the JSON. It works for 30 days after the run unless the site is deleted; take it from here when a person opens the site rather than storing it. Null when that run has no stored report.reportedAtstring (ISO 8601) · nullablerequiredWhen the run behindreportUrlwas made.
performanceanyrequiredThe usual and recent response time, and the open slowdown warning.linksobjectrequiredShow 2 child fieldsHide 2 child fields
monitorstringrequiredstatusPageobject · nullablerequiredShow 3 child fieldsHide 3 child fields
namestringrequiredurlstringrequiredprivatebooleanrequired
- 401
- Unauthorized. The original error shape:
{ "error": "text" }. - 403
- Forbidden. The original error shape:
{ "error": "text" }. - 404
- Not found. The original error shape:
{ "error": "text" }. - 429
- Too many requests. The original error shape:
{ "error": "text" }.
{
"generatedAt": "2026-11-10T09:30:00Z",
"site": {
"id": "string",
"name": "string",
"url": "string",
"kind": "string",
"enabled": true,
"state": "up",
"checkedAt": "2026-11-10T09:30:00Z",
"latencyMs": 0,
"statusCode": 0,
"error": "string",
"incident": {
"id": "string",
"startedAt": "2026-11-10T09:30:00Z",
"error": "string"
}
},
"uptime": {
"days30": 0,
"days90": 0
},
"days": [
{
"date": "string",
"monitored": true,
"downtimeMinutes": 0,
"incidents": 0
}
],
"latency24h": {
"hourly": [
0
],
"avgMs": 0
},
"ssl": {
"valid": true,
"expiresAt": "2026-11-10T09:30:00Z"
},
"domainExpiresAt": "2026-11-10T09:30:00Z",
"incidents": [
{
"id": "string",
"startedAt": "2026-11-10T09:30:00Z",
"endedAt": "2026-11-10T09:30:00Z",
"error": "string"
}
],
"pagespeed": {
"checkedAt": "2026-11-10T09:30:00Z",
"error": "string",
"url": "string",
"latest": {
"at": "2026-11-10T09:30:00Z",
"score": 0,
"accessibility": 0,
"bestPractices": 0,
"seo": 0,
"lcpMs": 0,
"cls": 0,
"inpMs": 0,
"source": "field"
},
"history": [
{
"at": "2026-11-10T09:30:00Z",
"score": 0
}
],
"field": {
"overall": "fast",
"lcp": {
"p75": 0,
"good": 0
},
"inp": {
"p75": 0,
"good": 0
},
"cls": {
"p75": 0,
"good": 0
}
},
"lab": {
"fcpMs": 0,
"lcpMs": 0,
"tbtMs": 0,
"cls": 0,
"speedIndexMs": 0
},
"audits": [
{
"title": "string",
"display": "string",
"savingsMs": 0
}
],
"issues": {
"accessibility": 0,
"bestPractices": 0,
"seo": 0
},
"reportUrl": "string",
"reportedAt": "2026-11-10T09:30:00Z",
"desktop": {
"latest": {
"at": "2026-11-10T09:30:00Z",
"score": 0,
"accessibility": 0,
"bestPractices": 0,
"seo": 0,
"lcpMs": 0,
"cls": 0,
"inpMs": 0,
"source": "field"
},
"history": [
{
"at": "2026-11-10T09:30:00Z",
"score": 0
}
],
"field": {
"overall": "fast",
"lcp": {
"p75": 0,
"good": 0
},
"inp": {
"p75": 0,
"good": 0
},
"cls": {
"p75": 0,
"good": 0
}
},
"lab": {
"fcpMs": 0,
"lcpMs": 0,
"tbtMs": 0,
"cls": 0,
"speedIndexMs": 0
},
"audits": [
{
"title": "string",
"display": "string",
"savingsMs": 0
}
],
"issues": {
"accessibility": 0,
"bestPractices": 0,
"seo": 0
},
"reportUrl": "string",
"reportedAt": "2026-11-10T09:30:00Z"
}
},
"links": {
"monitor": "string",
"statusPage": {
"name": "string",
"url": "string",
"private": true
}
}
}Get this OpenAPI document
GET/openapi.json
The OpenAPI 3.1 document of this API, built from the same schemas the API validates with. Public: no token needed.
Returns
200The document.
{}