Documentation
What to send us, what we send you, and what every answer means — enough to wire something up before you have an account.
Reporting a job in
One request, no key and no client library. Every check you create gets its own URL; the last part of it is the whole of what identifies the check, so treat it as a secret.
https://silentoutage.com/ping/your-ping-token
Replace your-ping-token with the value shown on your own check’s page. It is not a key you configure anywhere: it is the URL itself, and anyone holding it can report that check in.
/starthttps://silentoutage.com/ping/your-ping-token/start
Call this before the work begins. It starts the clock, so the run’s duration is measured rather than guessed, and a job that starts and then hangs is still reported late.
the URL on its ownhttps://silentoutage.com/ping/your-ping-token
Call this when the work finished cleanly. This is the bare URL with nothing appended, which is what a one-line addition to a crontab reaches.
/failhttps://silentoutage.com/ping/your-ping-token/fail
Call this when the work ran and did not succeed. The check is reported as failing at once.
/<exit status>https://silentoutage.com/ping/your-ping-token/$?
Append the number a command exited with — 0 through 255 — and we read 0 as a success and anything else as a failure. In a shell that is `$?`, which is why the crontab example below ends the way it does.
Command line
curl -fsS -m 10 https://silentoutage.com/ping/your-ping-token
Add /start before the job and /$? after it to record a duration and the status it exited with.
In a crontab
0 3 * * * /usr/local/bin/nightly-report; curl -fsS -m 10 "https://silentoutage.com/ping/your-ping-token/$?"
Your own schedule and command go where the example’s are; the rest is the reporting half.
Raw HTTP
POST /ping/your-ping-token HTTP/1.1 Host: silentoutage.com
The whole protocol: no key, no header, no body needed. Any language can send it.
- GET, HEAD and POST all work, because a job wrapper reaches it with whichever its author had to hand.
- The answer is 200 as soon as the report is written down and after nothing else, so a wrapper never waits on us and a burst of jobs on the hour cannot be dropped.
- A body is kept and cut short at 10 KiB rather than being rejected — the last lines of a failing job are worth more than a tidy error.
- Nothing is retried on your side: if a report does not arrive, the check is reported late, which is the outcome the check exists for.
The REST API
Every route below is answered with a key you mint while signed in, carrying the scopes you choose and nothing they do not cover. A key never reaches another account: something belonging to somebody else is not found rather than refused. It is shown to you once, when it is created, and is held as a digest afterwards.
/api/v1/openapi.json — The machine-readable description of the same routes, generated from the list this page is generated from, so a client written against it cannot be written against something we do not serve. It needs no key.
GET /api/v1/openapi.jsonThis OpenAPI document
GET /api/v1/projectsList the projects this key’s account owns
POST /api/v1/projectsCreate a project
GET /api/v1/projects/{projectId}Read one project
PATCH /api/v1/projects/{projectId}Rename a project or move its business timezone
DELETE /api/v1/projects/{projectId}Delete an empty project
GET /api/v1/projects/{projectId}/statusCurrent state of every check in a project, plus its open incidents
GET /api/v1/projects/{projectId}/checksList a project’s checks
POST /api/v1/projects/{projectId}/checksCreate a check
GET /api/v1/projects/{projectId}/checks/{checkId}Read one check
PATCH /api/v1/projects/{projectId}/checks/{checkId}Rename a check or replace its config
DELETE /api/v1/projects/{projectId}/checks/{checkId}Delete a check
POST /api/v1/projects/{projectId}/checks/{checkId}/pausePause a check — the deploy-window button
POST /api/v1/projects/{projectId}/checks/{checkId}/resumeResume a paused check
GET /api/v1/projects/{projectId}/checks/{checkId}/pingsA check’s ping history
GET /api/v1/projects/{projectId}/incidentsA project’s incidents, newest first
GET /api/v1/projects/{projectId}/incidents/{incidentId}Read one incident
POST /api/v1/incidents/{incidentId}/acknowledgeAcknowledge an incident — halt escalation, leave it open
POST /api/v1/incidents/{incidentId}/resolveResolve an incident — close the record
GET /api/v1/channelsList the account’s alert destinations — metadata only
POST /api/v1/channelsAdd an email destination
GET /api/v1/channels/{channelId}Read one destination’s metadata
DELETE /api/v1/channels/{channelId}Remove a destination
Served somewhere else
The path above is answered by the part of the system that receives reports, and with no key. Which origin answers it is a fact about the deployment and is shown with the path rather than assumed. It is the same request the section above documents in full.
POST /ping/{token}Report a heartbeat, a job result, or a business event
Scopes
A key carries the scopes you give it and nothing is implied by anything else. A request outside them is refused without touching your data.
projects:readGET /api/v1/projectsGET /api/v1/projects/{projectId}
projects:writePOST /api/v1/projectsPATCH /api/v1/projects/{projectId}DELETE /api/v1/projects/{projectId}
checks:readGET /api/v1/projects/{projectId}/checksGET /api/v1/projects/{projectId}/checks/{checkId}GET /api/v1/projects/{projectId}/checks/{checkId}/pings
checks:writePOST /api/v1/projects/{projectId}/checksPATCH /api/v1/projects/{projectId}/checks/{checkId}DELETE /api/v1/projects/{projectId}/checks/{checkId}POST /api/v1/projects/{projectId}/checks/{checkId}/pausePOST /api/v1/projects/{projectId}/checks/{checkId}/resume
incidents:readGET /api/v1/projects/{projectId}/incidentsGET /api/v1/projects/{projectId}/incidents/{incidentId}
incidents:writePOST /api/v1/incidents/{incidentId}/acknowledgePOST /api/v1/incidents/{incidentId}/resolve
channels:readGET /api/v1/channelsGET /api/v1/channels/{channelId}
channels:writePOST /api/v1/channelsDELETE /api/v1/channels/{channelId}
status:readGET /api/v1/projects/{projectId}/status
The long-form documents
Everything above in more depth, and the parts of the product that are not a request you make.
The REST API
Everything the dashboard does, over HTTP, with a key you scope yourself — projects, checks, incidents and where alerts go.
The Node and Python SDKs
Two dependency-free wrappers around the same request, written so that nothing they do can raise inside your application. The document says where each one can be had today.
Outbound webhooks
What we post to a URL of yours when an incident opens, is acknowledged or closes, and how to check the signature on it.
The Model Context Protocol server
The seven tools an agent can call to ask about your monitoring, and the scope each one needs.
Telling your outage from your provider’s
How the verdict on an alert is reached, what evidence it rests on, and when the honest answer is that we cannot tell.
Which of your destinations receive a page
The rules that decide who is contacted for an incident, why an unconfirmed destination is never one of them, and how escalation moves between them.
Running this yourself
The licence, what it asks of you if you host a modified copy, and where the source of the version you are talking to is.
Data processing agreement
The template we offer customers, with the technical measures and the list of other companies involved kept in step with the code.