Documentation

Pingdot Public API

Integrate uptime data into any tool. Access monitors, incidents, and status pages programmatically.

v1.0REST APIJSONRead-only

Overview

The pingdot API lets you programmatically access your monitors, incidents, and status page data.

4 Endpoints

Read-only JSON

7 Event Types

Real-time push

API Key Auth

Bearer token

Base URL: https://pingdot.io — All requests require authentication.

Quick Start

1

Get your API key

Go to SettingsProject SettingsAPI Keys tab. Copy the key — it's only shown once.

2

Make your first request

curl
curl https://pingdot.io/api/v1/status/your-slug \
  -H "Authorization: Bearer pk_your_api_key"
3

Parse the response

response.json
{
  "status": "operational",
  "monitors": [
    {
      "id": "mon_xxxx",
      "name": "API",
      "status": "up",
      "uptimePercentage": 99.9
    }
  ],
  "incidents": []
}

Authentication

All API requests must include your API key as a Bearer token in the Authorization header.

Keep your API key secret. Do not expose it in client-side code or public repositories.

Request header

Authorization header
Authorization: Bearer pk_live_xxxxxxxxxxxx

Getting your API key

  1. 1.Go to your Dashboard
  2. 2.Open Project Settings
  3. 3.Click the API Keys tab
  4. 4.Click Generate Key and copy it immediately

Endpoints

MethodEndpoint
GET/api/v1/status/:slug
GET/api/v1/monitors/:slug
GET/api/v1/incidents/:slug
GET/api/v1/components/:slug
Rate limit: 60 requests/minute per API key.

Example — GET /api/v1/status/:slug

curl
curl https://pingdot.io/api/v1/status/your-slug \
  -H "Authorization: Bearer pk_your_api_key"
response.json
{
  "id": "proj_xxxx",
  "name": "My Project",
  "status": "operational",
  "monitors": [
    {
      "id": "mon_xxxx",
      "name": "API",
      "url": "https://api.example.com",
      "status": "up",
      "lastCheckedAt": "2026-02-22T10:30:00Z",
      "uptimePercentage": 99.9
    }
  ],
  "incidents": []
}

Webhooks

Receive real-time HTTP POST notifications when monitor status changes or incidents are created.

Configuration

  1. 1.Go to Project Settings → Notifications
  2. 2.Add your webhook URL (must be HTTPS)
  3. 3.Optionally set a secret for HMAC verification
  4. 4.Save and test with the "Send test" button

Payload format

payload.json
{
  "event": "monitor_down",
  "timestamp": "2026-02-22T10:30:00Z",
  "data": {
    "monitor": {
      "id": "mon_xxxx",
      "name": "API",
      "url": "https://api.example.com",
      "errorType": "timeout",
      "errorMessage": "Connection timed out after 10s"
    }
  }
}

HTTP headers

Content-Typeapplication/json
X-Pingdot-Eventmonitor_down
X-Pingdot-Signaturesha256=xxxx
X-Pingdot-Timestamp1708596600

Event Types

All events include the same base payload format. The event field identifies the type.

Event
monitor_down
monitor_up
incident_created
incident_updated
incident_resolved
maintenance_scheduled
maintenance_started

HMAC Verificationoptional

Optional but recommended. Verify that webhook payloads originate from pingdot.

When you set a webhook secret, we sign every payload with HMAC-SHA256. Verify the signature in your endpoint handler:

verify.ts (Node.js)
import crypto from 'crypto'

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf-8')
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

The signature value comes from the X-Pingdot-Signature header. Always use timingSafeEqual to prevent timing attacks.

Questions? support@pingdot.io

Go to Dashboard