Centre d'aide / Développeurs

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.

Spécification OpenAPI 3.1 (YAML) Jetons d'API

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/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.