API Pingerer
Manage sites, monitors, incidents, heartbeats, alerts, quiet hours, status pages and maintenance, and read check results, site health and Internet weather.
Every request needs an API token, sent as `Authorization: Bearer `.
Create one on the API tokens page; a token can be read only, and can be
limited to one account.
Requests are for one account: the `Pingerer-Account` header (an account id
like `acct_...`, or its number) or the `account_id` parameter picks it.
Without either, it's the token's account, else your first team account,
else your personal one. An account paused by Pingerer answers
`403 account_suspended`.
Responses are `{"data": ..., "meta": {...}}`. Lists are paginated with
`page` and `per_page` (up to 100, 20 by default), and `meta` has `page`,
`per_page`, `total`, `total_pages`, `next_page` and `prev_page`. Errors are
`{"error": "code", "message": "...", "details": {...}}`: `bad_request`
(400), `unauthorized` (401), `forbidden`, `read_only_token`,
`account_suspended` and `password_change_required` (403), `not_found`
(404), `validation_failed` and `plan_limit` (422), `rate_limited` (429).
Each token may make 300 requests a minute.
Ids are stable prefixed ids (`site_...`, `mon_...`). PUT and PATCH
change only the fields sent (except a monitor's settings, which PUT
replaces), so sending the same request twice changes nothing more. A
command-line tool, a Terraform provider and a GitHub Action built on
these endpoints are coming soon (not published yet).
Durations (`every`, `grace`, `since`, `duration`) take seconds or `30s`, `5m`, `1h`,
`1d`, `1w`. Times are ISO 8601.
Démarrage rapide
curl https://pingerer.com/api/v1/status \
-H "Authorization: Bearer $PINGERER_TOKEN"
L'API et les webhooks sont disponibles. Pour recevoir les alertes dans votre propre code, ajoutez un canal d'alerte webhook : ce que reçoit un webhook.
Outil en ligne de commande et GitHub Action
Tous deux reposent sur les points de terminaison ci-dessous.
- L'outil en ligne de commande (
pingerer) pour votre terminal et votre CI :brew install pingerer-app/tap/pingerer. - La GitHub Action met les alertes en pause ou ouvre une fenêtre de maintenance pendant votre déploiement, puis attend que votre site soit de nouveau en ligne.
Bientôt : Terraform
Un provider Terraform pour gérer sous forme de code les sites, les surveillances, les canaux et règles d'alerte, les pages de statut, leurs composants et les fenêtres de maintenance. D'ici là, l'API fait tout cela.
Points de terminaison
Account
GET /api/v1/me
The person the token belongs to
Works for any account, even a paused one. The CLI's `login` checks a token with it.
curl https://pingerer.com/api/v1/me \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/me
Change your own settings
Your name, time zone (like Asia/Kuwait), briefing email (off, weekly or daily) and incidents under the bell.
curl -X PATCH https://pingerer.com/api/v1/me \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/accounts
Your accounts
Every account you belong to (a plain array). Use an id in the Pingerer-Account header.
curl https://pingerer.com/api/v1/accounts \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/push_devices
Your devices for push alerts
The phones and tablets the Pingerer app registered for you (docs/mobile-apps.md).
curl https://pingerer.com/api/v1/push_devices \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/push_devices
Register a device for push alerts
What the apps call on each launch. Registering a token again
updates its device. A token registered by someone else moves to
you only with that install's `install_id` (a random id the app
makes once per install), else 409. `environment` is `sandbox` for
iOS debug builds only.
curl -X POST https://pingerer.com/api/v1/push_devices \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"token":"a1b2c3…","platform":"ios","install_id":"4f1c9a7e-2b3d-4e5f-8a9b-0c1d2e3f4a5b","name":"Sam's iPhone","app_version":"1.4"}'
POST /api/v1/push_devices/live_activity
Your iPhone's lock-screen outage token
The iOS app's push-to-start token for the lock-screen outage (a Live
Activity, iOS 17.2 and up): Pingerer starts one on this phone when a
site goes down. `token` is the device's push token from
`POST /api/v1/push_devices`; without it, your newest iPhone.
curl -X POST https://pingerer.com/api/v1/push_devices/live_activity \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"token":"a1b2c3…","start_token":"80c1d2…"}'
POST /api/v1/live_activities
One lock-screen outage's token
Sent by the iOS app when a lock-screen outage starts, with that
activity's own push token, so Pingerer can end it when the site is
back.
curl -X POST https://pingerer.com/api/v1/live_activities \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"incident_id":"inc_8Ux2","token":"f0e1d2…"}'
DELETE /api/v1/push_devices/{id}
Remove a device (on sign-out)
curl -X DELETE https://pingerer.com/api/v1/push_devices/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/status
The account at a glance
Overall status (down, degraded, up or pending), sites and monitors counted by status, down sites and unresolved incidents.
curl https://pingerer.com/api/v1/status \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/insights
What's worth doing
What Pingerer itself would do next in the workspace, worst first, and one sentence that sums it up:
what's wrong now, sites whose alerts reach nobody, alert channels that are failing or unconfirmed,
checks that only repeat another, and (once turned on for the workspace) checks that alert for blips,
sites getting slower and trouble that comes back at the same time. Nothing is done by reading it.
curl https://pingerer.com/api/v1/insights \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/briefing
Your briefing (the apps' Home)
The same briefing as the Sites page: a calm headline when all is well, what needs you now,
quick answers, what's already sorted, what can wait and what's coming up. Reading it counts as looking.
curl https://pingerer.com/api/v1/briefing \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/undo
Undo a delete, resolve, unpublish or pause
Deleting a site, monitor, heartbeat or status page, resolving an incident, unpublishing a status page and
pausing a site answer with a `Pingerer-Undo-Token` header. Post it here within 10 minutes to put things back.
410 `undo_expired` when it's too late or not for this account.
curl -X POST https://pingerer.com/api/v1/undo \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/team
The team: members, invitations, two-step rule
Members with their roles, open invitations (admins) and whether two-step sign-in is required.
curl https://pingerer.com/api/v1/team \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/team
Require two-step sign-in for the team (admins)
422 `two_step_needed` until the admin has turned it on for themselves.
curl -X PATCH https://pingerer.com/api/v1/team \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/members/{id}
Change a member's roles (admins)
curl -X PATCH https://pingerer.com/api/v1/members/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/members/{id}
Remove a member (admins; not the owner)
curl -X DELETE https://pingerer.com/api/v1/members/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/invitations
Invite someone (admins)
curl -X POST https://pingerer.com/api/v1/invitations \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/invitations/{id}
Take an invitation back (admins)
curl -X DELETE https://pingerer.com/api/v1/invitations/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/invitations/{id}/resend
Send an invitation again (admins)
curl -X POST https://pingerer.com/api/v1/invitations/mon_8xKq2/resend \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/security
Your account's security checklist
Two-step sign-in, a passkey, backup codes saved and no forgotten tokens: which are done.
curl https://pingerer.com/api/v1/security \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/sign_ins
Where you're signed in
Browsers (`session_…`) and phones with the app (`token_…`); the phone asking is `current`.
curl https://pingerer.com/api/v1/sign_ins \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/sign_ins/{id}
Sign one out
422 `current` for the phone asking: sign out with DELETE /api/v1/auth.
curl -X DELETE https://pingerer.com/api/v1/sign_ins/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/sign_ins/sign_out_others
Sign out everywhere else
curl -X POST https://pingerer.com/api/v1/sign_ins/sign_out_others \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/passkeys
Your passkeys
curl https://pingerer.com/api/v1/passkeys \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/passkeys/{id}
Remove a passkey
curl -X DELETE https://pingerer.com/api/v1/passkeys/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/activities
Who changed what (admins)
curl https://pingerer.com/api/v1/activities \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/announcements
What's new
Newest first, with `unread` for you.
curl https://pingerer.com/api/v1/announcements \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/announcements/read
Mark everything in What's new as read
curl -X POST https://pingerer.com/api/v1/announcements/read \
-H "Authorization: Bearer $PINGERER_TOKEN"
Sites
GET /api/v1/sites
List sites
In the same order as the Sites page, grouped by `group` (sites in no group last), then the order people set (`position`), then by name.
curl https://pingerer.com/api/v1/sites \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/sites
Add a site
Adds the site and a monitor for each of `kinds` (default http, ssl,
domain, dns, email_auth). `every` sets how often the uptime kinds
(http, tcp, ping, smtp) check; the plan's shortest by default. `detect: true`
looks the site up first to fill in each check's settings.
`create_monitors: false` adds the site alone (Terraform adds each
monitor itself), and `paused: true` adds it paused.
curl -X POST https://pingerer.com/api/v1/sites \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"yourbakery.com","kinds":["http","ssl","domain"],"every":"1m"}'
POST /api/v1/sites/detect
Look a site up before adding it
What Pingerer finds for an address (certificate, domain, DNS, email) and the checks it suggests.
curl -X POST https://pingerer.com/api/v1/sites/detect \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"yourbakery.com"}'
GET /api/v1/sites/{id}
A site and its monitors
curl https://pingerer.com/api/v1/sites/yourbakery.com \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/sites/{id}
Rename, group, pause or resume a site
`paused` pauses or resumes it, like the pause and resume endpoints. `group` puts it in a group on the Sites page (empty for none). PUT works the same, and sending the same body twice changes nothing.
curl -X PATCH https://pingerer.com/api/v1/sites/yourbakery.com \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Your Bakery","group":"Clients","paused":false}'
DELETE /api/v1/sites/{id}
Delete a site, its monitors, results and incidents
curl -X DELETE https://pingerer.com/api/v1/sites/yourbakery.com \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/sites/{id}/pause
Pause a site and its monitors
curl -X POST https://pingerer.com/api/v1/sites/yourbakery.com/pause \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/sites/{id}/resume
Resume a site and the monitors pausing it stopped
curl -X POST https://pingerer.com/api/v1/sites/yourbakery.com/resume \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/sites/{id}/uptime
Uptime of a site's uptime monitors over 24h, 7d, 30d and 90d
curl https://pingerer.com/api/v1/sites/yourbakery.com/uptime \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/sites/{site_id}/health
A site's health score and what to fix
The latest site health check, as on the site's Health page: a score
out of 100, how it moved since the check before, and every finding
by area (HTTPS, security headers, DNS, email, domain and link
previews), each with a plain-English fix. We check every site once
a week. `score` is null until the first check finishes, and
`running` is true while one is going. `history` is the last few
scores, oldest first. Any member can read it.
curl https://pingerer.com/api/v1/sites/yourbakery.com/health \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/sites/{site_id}/health
Check a site's health now
Like Check now on the Health page: starts a new check in the
background and answers 202 straight away. Poll the GET above until
`running` is false (a minute or two). Admins only, on a read and
write token. One at a time per site (409 `already_running`), and
at most once every 10 minutes (429 `too_soon`, with a `Retry-After`
header and `details.retry_after_seconds`).
curl -X POST https://pingerer.com/api/v1/sites/yourbakery.com/health \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/sites/{id}/dns_changes
A site's DNS changes
Newest first, each record with its values before and after.
curl https://pingerer.com/api/v1/sites/yourbakery.com/dns_changes \
-H "Authorization: Bearer $PINGERER_TOKEN"
Monitors
GET /api/v1/monitors
List monitors
curl https://pingerer.com/api/v1/monitors \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/monitors
Add a monitor to a site
`settings` are the kind's (for http: url, http_method, expected_statuses, keyword, keyword_absent, max_response_ms, follow_redirects, headers; for domain: domain, warn_days and renews_on; see the Monitor schema for every kind). A multi-step check (kind steps, paid plans) takes `settings.steps` (up to 10 of name, method, url, headers, body_type none/form/json, body, follow_redirects, assertions [{type, field, value}] and extract [{name, from, field}]) and `secrets`, its secret variables (write-only, always shown masked).
curl -X POST https://pingerer.com/api/v1/monitors \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"site_id":"yourbakery.com","kind":"tcp","name":"Port 22","settings":{"host":"yourbakery.com","port":22}}'
GET /api/v1/monitors/{id}
A monitor
curl https://pingerer.com/api/v1/monitors/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/monitors/{id}
Change a monitor
Settings given are merged into the current ones. With PUT instead,
they replace them: settings left out go back to their defaults.
`paused` pauses or resumes it. Fields left out stay as they are.
Some registries keep renewal dates private (.kw, .sa, .ae, .qa, .om,
.io, .co and others). For those, set a domain check's
`settings.renews_on` to the date you renew by, like `2027-03-02`,
and we remind you before it's due. Send null to clear it.
curl -X PATCH https://pingerer.com/api/v1/monitors/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"every":"5m","settings":{"keyword":"Open today"}}'
DELETE /api/v1/monitors/{id}
Delete a monitor and its results
curl -X DELETE https://pingerer.com/api/v1/monitors/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/monitors/{id}/pause
Pause a monitor
curl -X POST https://pingerer.com/api/v1/monitors/mon_8xKq2/pause \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/monitors/{id}/resume
Resume a monitor
A plan with no room for another active monitor answers 422 plan_limit.
curl -X POST https://pingerer.com/api/v1/monitors/mon_8xKq2/resume \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/monitors/{id}/test
Run one check now
Checks once from `region` (default the monitor's first) and returns the result without recording it.
curl -X POST https://pingerer.com/api/v1/monitors/mon_8xKq2/test \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/monitors/{id}/uptime
Uptime of a monitor over 24h, 7d, 30d and 90d
curl https://pingerer.com/api/v1/monitors/mon_8xKq2/uptime \
-H "Authorization: Bearer $PINGERER_TOKEN"
Results
GET /api/v1/monitors/{monitor_id}/results
A monitor's check results, newest first
curl https://pingerer.com/api/v1/monitors/mon_8xKq2/results \
-H "Authorization: Bearer $PINGERER_TOKEN"
Incidents
GET /api/v1/incidents
List incidents, newest first
curl https://pingerer.com/api/v1/incidents \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/incidents/{id}
An incident and its timeline
curl https://pingerer.com/api/v1/incidents/INC-0042 \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/incidents/{id}/acknowledge
Acknowledge an incident
Stops escalation. Any member may acknowledge.
curl -X POST https://pingerer.com/api/v1/incidents/INC-0042/acknowledge \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/incidents/{id}/snooze
Snooze an expiry's reminders
No more reminders about an expiring certificate or domain for 3 days, as from the alert email. Any member may snooze. Only incidents with snoozable true can be snoozed; acknowledge others.
curl -X POST https://pingerer.com/api/v1/incidents/INC-0042/snooze \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/incidents/{id}/notes
Add a note to an incident's timeline
curl -X POST https://pingerer.com/api/v1/incidents/INC-0042/notes \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Restarted the web server"}'
POST /api/v1/incidents/{id}/resolve
Resolve an incident
curl -X POST https://pingerer.com/api/v1/incidents/INC-0042/resolve \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message":"Fixed by the host"}'
Heartbeats
GET /api/v1/heartbeats
List heartbeats
curl https://pingerer.com/api/v1/heartbeats \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/heartbeats
Add a heartbeat
Your job requests the returned `ping_url` each time it runs. No ping within `every` plus `grace` opens an incident. With `email_pings` (where Pingerer has turned on email heartbeats for the account), an email to `ping_email` counts as a ping too; a subject with "failed" in it reports a failure.
curl -X POST https://pingerer.com/api/v1/heartbeats \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Nightly backup","every":"1d","grace":"30m"}'
GET /api/v1/heartbeats/{id}
A heartbeat
curl https://pingerer.com/api/v1/heartbeats/mon_5hB1 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/heartbeats/{id}
Change a heartbeat
curl -X PATCH https://pingerer.com/api/v1/heartbeats/mon_5hB1 \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"every":"12h"}'
DELETE /api/v1/heartbeats/{id}
Delete a heartbeat
curl -X DELETE https://pingerer.com/api/v1/heartbeats/mon_5hB1 \
-H "Authorization: Bearer $PINGERER_TOKEN"
Alerts
GET /api/v1/alert_channels
List alert channels and their rules
curl https://pingerer.com/api/v1/alert_channels \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/alert_channels
Add an alert channel
Settings by kind: email `addresses`; slack `webhook_url` and `channel`;
discord and teams `webhook_url`; telegram `chat_id`; webhook `url`
(its signing secret is in this response only); sms `numbers`; push
`user_ids` (members' ids or emails; none means everyone with the
app) and `critical`, once Pingerer's push is set up.
`site_ids` limits it to some sites (default every site), and `events`
to some events (default all); `default_rule: false` adds no rule, for
adding each one with POST /api/v1/alert_rules. Email to an address
that isn't a member's is sent a confirmation link first.
curl -X POST https://pingerer.com/api/v1/alert_channels \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"kind":"webhook","name":"Ops webhook","url":"https://ops.example.com/pingerer"}'
GET /api/v1/alert_channels/{id}
An alert channel
curl https://pingerer.com/api/v1/alert_channels/ach_3Lm9 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/alert_channels/{id}
Change an alert channel
Changes `name`, `enabled` and the kind's settings that are sent (the
same as when adding one); the rest stay as they are, so secrets
needn't be sent again. A new destination needs verifying again. The
kind can't change. PUT works the same.
curl -X PATCH https://pingerer.com/api/v1/alert_channels/ach_3Lm9 \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Ops team","enabled":true}'
DELETE /api/v1/alert_channels/{id}
Delete an alert channel
curl -X DELETE https://pingerer.com/api/v1/alert_channels/ach_3Lm9 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/alert_rules
List alert rules
Which sites' events go to which channel. A rule with no site covers every site, new ones too.
curl https://pingerer.com/api/v1/alert_rules \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/alert_rules
Send a site's events to a channel
`site_id` (an id or host; leave it out for every site), `events`
(default all) and `escalate_after_minutes` (alert this channel only
if an incident is still unacknowledged that long). A channel has one
rule per site.
curl -X POST https://pingerer.com/api/v1/alert_rules \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"alert_channel_id":"ach_3Lm9","site_id":"yourbakery.com","events":["down","recovered"]}'
GET /api/v1/alert_rules/{id}
An alert rule
curl https://pingerer.com/api/v1/alert_rules/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/alert_rules/{id}
Change an alert rule
Changes the fields sent (`site_id` null for every site); the channel can't change. PUT works the same.
curl -X PATCH https://pingerer.com/api/v1/alert_rules/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"events":["down"],"escalate_after_minutes":15}'
DELETE /api/v1/alert_rules/{id}
Delete an alert rule
curl -X DELETE https://pingerer.com/api/v1/alert_rules/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/quiet_hours
Quiet hours and the weekend
Quiet hours hold back the alerts that can wait (SSL certificates,
domains, DNS changes, email setup and slowness) overnight, and all
weekend when `weekends` is on. Downtime and missed heartbeats always
go through. The held alerts arrive when quiet hours end.
`weekend` is the account's choice of weekend, or null to go by the
time zone: Friday and Saturday in the Gulf and much of the Middle
East, Saturday and Sunday elsewhere. `effective_time_zone`,
`effective_weekend` and `weekend_days` say what's actually used.
Anyone who can see the Alerts page can read them.
curl https://pingerer.com/api/v1/quiet_hours \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/quiet_hours
Change quiet hours or the weekend
Admins only. Fields left out stay as they are; PUT works the same.
`starts` and `ends` are 24-hour times like `22:00` and may wrap past
midnight. A blank `time_zone` uses the account owner's, and a blank
`weekend` goes back to the time zone's usual one.
curl -X PATCH https://pingerer.com/api/v1/quiet_hours \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled":true,"starts":"22:00","ends":"07:00","time_zone":"Asia/Kuwait","weekends":true,"weekend":"fri_sat"}'
GET /api/v1/on_call_schedules
On-call schedules
Who's on call now and next, the rotation and overrides. `meta.allowed` says whether the account can use on-call; `meta.can_manage` whether you can change schedules.
curl https://pingerer.com/api/v1/on_call_schedules \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/on_call_schedules
Make an on-call schedule (admins)
curl -X POST https://pingerer.com/api/v1/on_call_schedules \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/on_call_schedules/{id}
An on-call schedule with the week ahead
curl https://pingerer.com/api/v1/on_call_schedules/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/on_call_schedules/{id}
Change an on-call schedule (admins)
curl -X PATCH https://pingerer.com/api/v1/on_call_schedules/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/on_call_schedules/{id}
Delete an on-call schedule (admins)
curl -X DELETE https://pingerer.com/api/v1/on_call_schedules/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/on_call_schedules/{on_call_schedule_id}/overrides
Cover a schedule for a while
Members cover themselves; admins can put anyone on with `user_id`. Times are ISO 8601.
curl -X POST https://pingerer.com/api/v1/on_call_schedules/{on_call_schedule_id}/overrides \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/on_call_schedules/{on_call_schedule_id}/overrides/{id}
Take a cover back
curl -X DELETE https://pingerer.com/api/v1/on_call_schedules/{on_call_schedule_id}/overrides/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
Regions
GET /api/v1/regions
Where checks run from
Every region, home first. `meta.max_per_monitor` is how many a
monitor may use on the account's plan (null for all), `meta.default`
the regions a new monitor gets, and `meta.min_interval_seconds` the
plan's shortest interval.
curl https://pingerer.com/api/v1/regions \
-H "Authorization: Bearer $PINGERER_TOKEN"
Tools
GET /api/v1/link_preview
How a page looks when its link is shared
Our free link preview checker, for any public page: the title,
description and picture Slack, WhatsApp, iMessage, Facebook,
LinkedIn and X show, and what's missing or broken, with how to fix
it. Site health checks each site's homepage the same way every
week; use this for other pages, like a menu or a product, before
you share them.
Private and internal addresses are refused (422). Answers are kept
for 5 minutes, and each person may check 10 pages a minute and 100
a day (429 `rate_limited`).
curl -G https://pingerer.com/api/v1/link_preview \
-H "Authorization: Bearer $PINGERER_TOKEN" \
--data-urlencode "url=yourbakery.com/menu"
GET /api/v1/internet_weather
Which hosts, CDNs and website builders are having trouble
Internet weather, as on pingerer.com/internet-weather: each company
many websites depend on, the share of the websites we watch on it
that are working right now, and whether it's having trouble (sites
belonging to several different customers went down on it within
`window_minutes`). Troubled companies come first. `outages` is the
past week's trouble, newest first.
Only shares, never how many sites or customers, or which. A company
is listed only once we watch enough websites on it, for enough
different customers.
curl https://pingerer.com/api/v1/internet_weather \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/internet_weather/{slug}
Is a company down right now?
One company, as on its "Is Cloudflare down?" page: `state` is
`trouble`, `clear`, or `unknown` when we don't watch enough websites
on it to say. `outages` covers the last 90 days.
curl https://pingerer.com/api/v1/internet_weather/cloudflare \
-H "Authorization: Bearer $PINGERER_TOKEN"
Status pages
GET /api/v1/status_pages
List status pages
curl https://pingerer.com/api/v1/status_pages \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/status_pages
Make a status page
Up to the plan's limit. The slug is made from the name unless given.
It isn't public until `published` is true. A `custom_domain` is
verified with the TXT record in `custom_domain_records`, then served
once its CNAME points at us.
curl -X POST https://pingerer.com/api/v1/status_pages \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Your Bakery","slug":"your-bakery","published":true}'
GET /api/v1/status_pages/{id}
A status page, its components and their status now
curl https://pingerer.com/api/v1/status_pages/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/status_pages/{id}
Change, publish or unpublish a status page
Changes the fields sent; the rest stay as they are. PUT works the same.
curl -X PATCH https://pingerer.com/api/v1/status_pages/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"published":true,"brand_color":"#2F45E8"}'
DELETE /api/v1/status_pages/{id}
Delete a status page, its components, updates and subscribers
curl -X DELETE https://pingerer.com/api/v1/status_pages/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/status_pages/{status_page_id}/components
A status page's components, in order
curl https://pingerer.com/api/v1/status_pages/{status_page_id}/components \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/status_pages/{status_page_id}/components
Add a component
A component follows sites (their uptime monitors) and monitors
(a heartbeat, say): `site_ids` takes ids or hosts. It goes last
unless `position` (0 is first) says otherwise.
curl -X POST https://pingerer.com/api/v1/status_pages/{status_page_id}/components \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Online shop","site_ids":["shop.yourbakery.com"]}'
GET /api/v1/status_pages/{status_page_id}/components/{id}
A component
curl https://pingerer.com/api/v1/status_pages/{status_page_id}/components/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/status_pages/{status_page_id}/components/{id}
Change or move a component
Changes the fields sent; `site_ids` and `monitor_ids` replace what it followed. `position` moves it, and the others move along. PUT works the same.
curl -X PATCH https://pingerer.com/api/v1/status_pages/{status_page_id}/components/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"position":0}'
DELETE /api/v1/status_pages/{status_page_id}/components/{id}
Remove a component
curl -X DELETE https://pingerer.com/api/v1/status_pages/{status_page_id}/components/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/status_pages/{status_page_id}/updates
A status page's updates, newest first
curl https://pingerer.com/api/v1/status_pages/{status_page_id}/updates \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/status_pages/{status_page_id}/updates
Post a status update
Posts to the page and emails its confirmed subscribers (when the page
is published). `components` maps a component's name or id to its
impact (an empty string leaves it out). Pass `thread_id` to follow
up on an earlier update: the title and components carry over, and
`resolved` marks them operational. Admins only.
curl -X POST https://pingerer.com/api/v1/status_pages/{status_page_id}/updates \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"state":"investigating","title":"Checkout errors","message":"We're looking into it.","components":{"Online shop":"partial_outage"}}'
GET /api/v1/status_pages/{status_page_id}/updates/{id}
A status update
curl https://pingerer.com/api/v1/status_pages/{status_page_id}/updates/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/status_pages/{status_page_id}/updates/{id}
Change an update's wording, state or components
Doesn't email subscribers again.
curl -X PATCH https://pingerer.com/api/v1/status_pages/{status_page_id}/updates/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/status_pages/{status_page_id}/subscribers
A status page's subscribers (admins)
curl https://pingerer.com/api/v1/status_pages/{status_page_id}/subscribers \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/status_pages/{status_page_id}/subscribers/{id}
Remove a subscriber
curl -X DELETE https://pingerer.com/api/v1/status_pages/{status_page_id}/subscribers/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
GET /api/v1/status_pages/{status_page_id}/qr_code
The page's QR code as a PNG
For the apps to show, save, share or print. Request it as `qr_code.png`.
curl https://pingerer.com/api/v1/status_pages/{status_page_id}/qr_code \
-H "Authorization: Bearer $PINGERER_TOKEN"
Maintenance
GET /api/v1/maintenance_windows
List maintenance windows
Newest first. `state` filters to `upcoming` (scheduled, in progress or repeating), `done` or `cancelled`.
curl https://pingerer.com/api/v1/maintenance_windows \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/maintenance_windows
Schedule maintenance
During the window checks keep running and are stored, but the affected
sites' monitors don't open incidents or send alerts, and the time
doesn't count against uptime. Times without an offset are local to
`time_zone` (the account's by default). `sites` takes ids or hosts;
or set `all_sites`. `recurrence: weekly` repeats on `days` (sun..sat;
the start's day by default) at the same local time.
`notify_subscribers_before` is hours before (default 24; `false` for
no email to status page subscribers).
For a deploy, `duration` (like `15m`) without `starts_at` starts it
now, and without `ends_at` ends it that long after it starts; the
title is then "Maintenance" unless given.
curl -X POST https://pingerer.com/api/v1/maintenance_windows \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Database upgrade","starts_at":"2026-10-14T02:00:00-04:00","ends_at":"2026-10-14T02:30:00-04:00","sites":["shop.yourbakery.com"]}'
GET /api/v1/maintenance_windows/{id}
A maintenance window
curl https://pingerer.com/api/v1/maintenance_windows/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
PATCH /api/v1/maintenance_windows/{id}
Change a maintenance window
Takes the same fields as scheduling one; those left out stay as they are.
curl -X PATCH https://pingerer.com/api/v1/maintenance_windows/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
DELETE /api/v1/maintenance_windows/{id}
Delete a maintenance window
curl -X DELETE https://pingerer.com/api/v1/maintenance_windows/mon_8xKq2 \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/maintenance_windows/{id}/cancel
Cancel a maintenance window
It stays in the list as cancelled and no longer holds anything back.
curl -X POST https://pingerer.com/api/v1/maintenance_windows/mon_8xKq2/cancel \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/maintenance_windows/{id}/end
End a maintenance window now
One in progress ends now (a weekly one also stops repeating), so its
history stays; one that hasn't started is cancelled; one that's over
is left as it is. Safe to call twice.
curl -X POST https://pingerer.com/api/v1/maintenance_windows/mon_8xKq2/end \
-H "Authorization: Bearer $PINGERER_TOKEN"
Reports
GET /api/v1/reports/{month}
A month's report
Overall uptime (every uptime monitor's checks together, so busier
monitors weigh more), incidents, downtime, average response, a row
per site and heartbeat against the account's SLA target, and what's
worth fixing. Maintenance windows don't count. The month in progress
is reported so far; a month that hasn't started is a bad request.
curl https://pingerer.com/api/v1/reports/{month} \
-H "Authorization: Bearer $PINGERER_TOKEN"
Clients
GET /api/v1/clients
List an agency's client workspaces
The account must be an agency (the Agency plan). Each client has its
own sites, alerts, status pages and reports, and shares the agency's
monitor pool. To work inside a client, pass its id in the
Pingerer-Account header.
curl https://pingerer.com/api/v1/clients \
-H "Authorization: Bearer $PINGERER_TOKEN"
POST /api/v1/clients
Add a client workspace
Agency admins only. The agency's members can open it; invite the client's own people from the Clients page.
curl -X POST https://pingerer.com/api/v1/clients \
-H "Authorization: Bearer $PINGERER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Your Bakery"}'
Des questions sur l'API ? Écrivez-nous et une vraie personne vous répondra.