api reference

Pinger API

Two families of endpoint.

Tools run a single diagnostic and return the result. They are public: a key is optional, and raises the rate limit from 30 to 300 requests a minute while attributing the call to your account.

Sites manage what Pinger monitors on your behalf. These require a key, which authenticates an account rather than a person, so it keeps working after whoever created it has gone.

Base URL https://api.pinger.ai
Spec OpenAPI 3.1.0 · v1.0.0 (raw JSON)
Keys Create one in the console
tools

One-off diagnostics. A key is optional.

GET /v1/tools/http-headers key optional

HTTP Headers

Status code and response headers, without following redirects.

Parameters
target query string, required The url to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/http-headers?target=https://example.com"
GET /v1/tools/ssl-checker key optional

SSL Certificate

Validity, expiry, issuer, chain, and the negotiated TLS version and cipher.

Parameters
target query string, required The domain to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/ssl-checker?target=example.com"
GET /v1/tools/redirect-chain key optional

Redirect Chain

Every hop, with loops and dead hops identified.

Parameters
target query string, required The url to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/redirect-chain?target=http://example.com"
GET /v1/tools/dns-lookup key optional

DNS Lookup

A, AAAA, MX, NS, TXT and CNAME records.

Parameters
target query string, required The domain to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/dns-lookup?target=example.com"
GET /v1/tools/dns-propagation key optional

DNS Propagation

How a record has spread across public resolvers worldwide.

Parameters
target query string, required The domain to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/dns-propagation?target=example.com"
GET /v1/tools/domain-expiry key optional

Domain Expiry

Registrar, registration dates and days remaining.

Parameters
target query string, required The domain to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/domain-expiry?target=example.com"
GET /v1/tools/whois-lookup key optional

WHOIS Lookup

Registration data, registrar, nameservers and status.

Parameters
target query string, required The domain to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/whois-lookup?target=example.com"
GET /v1/tools/email-security key optional

SPF / DKIM / DMARC

Email authentication records, including the DMARC policy.

Parameters
target query string, required The domain to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/email-security?target=example.com"
GET /v1/tools/url-ping key optional

URL Ping

DNS, connect, TLS and time to first byte, sampled repeatedly.

Parameters
target query string, required The url to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/url-ping?target=https://example.com"
GET /v1/tools/ai-crawlers key optional

AI Crawler Check

Resolved access for 28 AI and search crawlers.

Parameters
target query string, required The domain to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/ai-crawlers?target=example.com"
GET /v1/tools/security-headers key optional

Security Headers

A weighted grade for the security headers a URL serves.

Parameters
target query string, required The url to check.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/security-headers?target=https://example.com"
GET /v1/tools/what-is-my-ip key optional

What Is My IP?

Public IP address with network and location. The target is optional.

Parameters
target query string The ip to check. Defaults to the caller's own address.
Responses
200 The check ran. The body is the result.
400 target was missing.
401 The key was invalid, revoked or expired.
422 The check could not complete. The target did not answer or returned something unusable. This is not a fault on our side.
429 Rate limited. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/v1/tools/what-is-my-ip"
sites

The sites Pinger monitors for your account.

GET /pinger/api/v1/sites

List sites

Parameters
active query boolean Filter to active or deactivated sites.
limit query integer
Responses
200 The account's sites. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/sites"
POST /pinger/api/v1/sites

Register a site

Checks start immediately rather than waiting for the next scheduled run.

Body
domain string, required
check_interval_minutes integer
alert_consecutive_failures integer
monitors object Monitors to enable or disable, by name.
Responses
201 The site as registered.
401 No valid credential.
422 The domain was invalid, or already monitored by this account. 
curl \
  -X POST \
  -H "Authorization: Bearer pi_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","check_interval_minutes":5,"alert_consecutive_failures":2,"monitors":{"sitemap":true,"dns":false}}' \
  "https://api.pinger.ai/pinger/api/v1/sites"
GET /pinger/api/v1/sites/{id}

Read one site

Parameters
id path string (uuid), required The site's uuid.
Responses
200 The site.
404 No such site on this account. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID"
PATCH /pinger/api/v1/sites/{id}

Update a site

The domain cannot be changed: a different domain is a different site.

Parameters
id path string (uuid), required The site's uuid.
Body
check_interval_minutes integer
alert_consecutive_failures integer
monitors object
Responses
200 The updated site.
404 No such site on this account.
422 The update was rejected. 
curl \
  -X PATCH \
  -H "Authorization: Bearer pi_live_..." \
  -H "Content-Type: application/json" \
  -d '{"check_interval_minutes":5,"alert_consecutive_failures":5,"monitors":{}}' \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID"
DELETE /pinger/api/v1/sites/{id}

Deactivate a site

Deactivation, never deletion. The check history stays attached and readable.

Parameters
id path string (uuid), required The site's uuid.
Responses
200 The deactivated site.
404 No such site on this account. 
curl \
  -X DELETE \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID"
POST /pinger/api/v1/sites/{id}/reactivate

Reactivate a site

Parameters
id path string (uuid), required The site's uuid.
Responses
200 The reactivated site.
404 No such site on this account. 
curl \
  -X POST \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID/reactivate"
monitors

Which checks run against a site.

GET /pinger/api/v1/sites/{id}/monitors

List a site's monitors

Parameters
id path string (uuid), required The site's uuid.
Responses
200 Every monitor, with whether it is on. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID/monitors"
PATCH /pinger/api/v1/sites/{id}/monitors

Turn monitors on or off

Monitors not named are left alone. An unknown name is reported rather than ignored, and nothing is applied.

Parameters
id path string (uuid), required The site's uuid.
Body
monitors object, required
Responses
200 The monitors as they now stand.
404 No such site on this account.
422 One of the names is not a monitor. 
curl \
  -X PATCH \
  -H "Authorization: Bearer pi_live_..." \
  -H "Content-Type: application/json" \
  -d '{"monitors":{"http":true,"ssl":true}}' \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID/monitors"
POST /pinger/api/v1/sites/{id}/checks

Run checks now

Queues the work and returns. A probe takes seconds, so nothing runs inline.

Parameters
id path string (uuid), required The site's uuid.
monitor query string Run one monitor rather than every enabled one.
Responses
202 Queued.
404 No such site on this account.
422 The site is deactivated, or the monitor is unknown, not enabled, or has no on-demand check. 
curl \
  -X POST \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID/checks"
incidents

Outages Pinger opened and resolved.

GET /pinger/api/v1/sites/{id}/incidents

A site's incidents

Parameters
id path string (uuid), required The site's uuid.
status query string
limit query integer
Responses
200 Incidents, newest first.
404 No such site on this account. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/sites/SITE_UUID/incidents"
account

Who the calling credential belongs to.

GET /pinger/api/v1/me

Who this credential is

Answers for both kinds of caller. A key identifies an account; a user token identifies a person.

Responses
200 The calling account.
401 No valid credential. 
curl \
  -H "Authorization: Bearer pi_live_..." \
  "https://api.pinger.ai/pinger/api/v1/me"