Automation API
Bearer authentication, endpoints, parameters, and responses.
Status exposes a bearer-key API for monitor automation, deployment ingestion, and incident integrations. Browser-only management routes are not a general public API. Create a key in Settings → Security & sessions or the Operations toolkit, give it only the needed scopes, and send:
Authorization: Bearer status_…
Content-Type: application/jsonA key is permanently bound to the organization active at creation. Responses
are JSON unless an export is returned as an attachment. Unknown fields are
rejected on strict request types. Errors use an HTTP status plus a JSON error
body; rate-limited endpoints also return Retry-After and limit headers.
Endpoint summary
| Method and path | Scope | Purpose |
|---|---|---|
GET /api/monitors | monitors:read | List organization monitors |
POST /api/monitors | monitors:write | Create one typed monitor |
PATCH /api/monitors/{id} | monitors:write | Replace typed configuration or send { "enabled": boolean } |
DELETE /api/monitors/{id} | monitors:write | Delete a monitor to the recycle bin |
GET /api/monitors/export | monitors:read | Download the versioned, secret-bearing package |
POST /api/monitors/import | monitors:write | Atomically import a versioned package |
GET /api/deployment-events | events:read | List deployment events |
POST /api/deployment-events | events:write | Idempotently ingest a deployment event |
GET /api/incidents | incidents:read | List incidents |
POST /api/incidents | incidents:write | Declare an incident |
PATCH /api/incidents/{id} | incidents:write | Add a public status update and change status |
DELETE /api/incidents/{id} | incidents:write | Delete an incident to the recycle bin |
POST /api/external-alerts | incidents:write | Ingest canonical or provider-shaped alert lifecycle events |
Write scope implies the corresponding read scope. API-key lifecycle endpoints, cross-organization monitor transfer, instance settings, team management, and other console administration remain session-only.
Monitors
Monitor create and update take a discriminated object: kind selects which
typed configuration applies, and the browser editor and the API run the same
validation. The fields below are the ones every kind shares. For the exact
current shape of one kind, export a representative monitor — but do not send the
outer transfer package back as a single-monitor create.
/api/monitorsEvery monitor in the organization, with its current state.
{ "monitors": [{ "id": "5a75c040-…", "name": "Checkout API", "status": "up" }] }/api/monitorsCreates one monitor. Unknown fields are rejected, including settings exported by a newer version that this instance does not support.
kindenumverplichtWhich check to run. Decides which type-specific fields the rest of the body must carry — see Monitoring.
namestringverplichtHow the monitor is listed and named in incidents and alerts.
intervalSecondsintegerverplichtHow often the check runs.
timeoutMsintegerverplichtHow long one attempt may take before it counts as a failure.
confirmationPeriodSecondsintegerverplichtHow long failure must persist before the monitor goes down. This is what keeps a single blip from paging anyone.
recoveryPeriodSecondsintegerverplichtHow long success must persist before a down monitor comes back up.
ipVersionenumverplichtWhich address family to check. dual checks both and is what
IPv4 and IPv6 availability describes.
regionsstring[]optioneelWhich worker locations run the check. Empty means any.
[]regelup to 20 namesagentIdsstring[]optioneelPrivate agents to pin the check to, for a target no shared worker can reach.
regionPolicyenumoptioneelHow many regions must agree before the result is accepted.
allretryCountintegeroptioneelImmediate retries before an attempt is recorded as a failure.
0regel0–5maxResponseTimeMsintegeroptioneelTreat a slow-but-successful check as a failure above this. 0 disables it.
0regel0–3600000dependencyIdsstring[]optioneelMonitors this one depends on. A failure while a dependency is down is suppressed rather than paged.
[]regelup to 20 UUIDstagsstring[]optioneelClassification, alongside folder and environment — see
Taxonomy and ownership.
[]regelup to 20, deduplicatedCarries the monitor, and for a heartbeat monitor its ingest URL — shown once.
Validation failed, or a referenced dependency, region or agent is not available to the organization.
/api/monitors/{id}Two accepted bodies, and which one you send decides what happens: the full typed
configuration replaces it, { "enabled": boolean } only pauses or resumes.
There is no partial update — a half-specified check is not a check.
idstringverplichtThe monitor's UUID.
enabledbooleanverplichtfalse stops scheduling without deleting anything or losing history.
/api/monitors/{id}Moves the monitor to the recycle bin, where it is restorable for 30 days. Its results go with it.
{ "deleted": true }Export and import are the stable bulk portability contract and accept at most 100 monitors atomically. They remap dependencies and return newly created heartbeat URLs once. See Import, export, and clone monitors.
Incidents
/api/incidentsEvery incident in the organization, newest first, each with its full public update timeline, assignment, acknowledgement and affected monitors.
/api/incidentsDeclares an incident. It opens as investigating with the message below as its
first public update.
titlestringverplichtWhat is wrong, in the words customers will read.
messagestringverplichtThe initial public incident update. Required when creating an incident.
severityenumverplichtImpact level. Agree your own examples for each — see Incidents.
monitorIdstring | nullverplichtThe monitor that detected it, or null for one you are declaring by hand. Must
belong to the organization.
componentIdsstring[]optioneelStatus-page components to mark as affected. Each must belong to a status page in this organization.
[]regelup to 100 UUIDs, deduplicated{
"incident": {
"id": "1f2e3d4c-5b6a-4788-9c0d-1e2f3a4b5c6d",
"title": "Checkout is failing",
"severity": "critical",
"status": "investigating",
"monitorId": "5a75c040-9383-4fe3-8c08-aa66c5f149d4",
"monitorName": "Checkout API",
"startedAt": "2025-12-01T12:00:00.000Z",
"resolvedAt": null,
"updates": [
{
"status": "investigating",
"message": "We are investigating failed checkouts.",
"visibility": "public",
"createdAt": "2025-12-01T12:00:00.000Z"
}
]
}
}The correlated monitor or one of the components does not belong to the organization.
/api/incidents/{id}Adds a public update and moves the incident's status. Both together: a status change with nothing said about it is what leaves a status page stale.
idstringverplichtThe incident's UUID.
statusenumverplichtWhere the response has got to. resolved closes the incident and stamps
resolvedAt.
messagestringverplichtThe public update. Appended to the timeline, attributed to the key's owner.
/api/incidents/{id}Moves the incident to the recycle bin for 30 days.
{ "deleted": true }External alert ingestion adds provider and external identity, firing/resolved idempotency, provider payload normalization, label-based grouping, and its own rate limit. Its full contract is in External alerts.
Security and limits
Treat exports and API responses that intentionally contain monitor configuration as secrets. Rotate a key to replace its bearer value immediately or revoke it while preserving audit history. See Scoped API keys, API rate limits, and Monitor credentials and secrets.