Documentation

Authentication

All API requests require authentication. Two methods are available: a personal API key (for most integrations) and a JWT token (for web applications and endpoints that don’t yet support the key).

API Key

Create a personal API key from your profile menu. Use the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" \
  https://pingzen.dev/api/v1/monitors

To create an API key: Click on your profile → API Keys → Create New Key

Zoom

Where X-API-Key works, and where JWT is required

Important

At this time, X-API-Key is accepted only on the monitors endpoints (CRUD, pause/resume, reorder, main statistics, and timeline). All other endpoints — /workspaces, /alerts, /incidents, /status-pages, /monitor-groups, /probes, /heartbeats (except the no-auth /ping/...), /maintenance, /feedback, /dashboard, /web-push, /scheduled-reports, /webhooks, /webhook-checks, /api-checks, /api-keys, /auth/*, /analytics, /telegram-bot, /alert-channel-configs — currently require a JWT token. This is a divergence from the historical promise of the docs; we’re closing it incrementally.

What X-API-Key covers right now:

Inside /monitors/*, these still require JWT (known divergence, being fixed): GET /:id/stats, POST /:id/check, GET /:id/sla, GET /:id/sla/export/csv|pdf, GET /:id/dnsbl/provider-history, POST /test.

JWT Token

For web applications and endpoints that don’t accept the API key, use a JWT from /auth/login:

# 1. Obtain a token (pass email and password)
ACCESS=$(curl -sS -X POST https://pingzen.dev/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

# 2. Use it as Authorization: Bearer
curl -H "Authorization: Bearer $ACCESS" https://pingzen.dev/api/v1/workspaces

The access token lives for 15 minutes; for long-running integrations use the refresh_token from the same response and the /auth/refresh endpoint.

Endpoints

Complete list of all available API endpoints.

Monitors

Monitor management (22 endpoints, grouped by purpose).

CRUD

Operations

Stats & history

Diagnostics

Alerts

Alert configuration.

Incidents

Incident management.

Status Pages

Public status pages.

Workspaces

Workspace management.

Heartbeats (Cron)

Cron job monitoring.

API Keys

API key management.

Maintenance

Maintenance windows.

Monitor Groups

Group management (12 endpoints, grouped by purpose).

Group CRUD

Memberships (monitors & tags)

Status & stats

Telegram Groups

Telegram group alerts.

Scheduled Reports

Automated email reports.

Alert Channel Configs

Channel credentials (SMTP, Twilio, etc.).

Dashboard

Aggregated statistics.

Webhooks (Outgoing)

Event webhook delivery (12 endpoints, grouped by purpose).

Webhook CRUD

Actions

Deliveries & DLQ

Reference

Webhook Checks (Incoming)

Accept incoming webhooks from external services (10 endpoints + 1 public receiver, grouped by purpose).

Check CRUD

Check operations

Events & stats

Public receiver (no auth)

Feedback

User feedback and feature requests.

Web Push

Browser push notifications.

Probe

Probe identification and IP addresses.

Request Examples

Detailed cURL examples.

List monitors

curl -H "X-API-Key: YOUR_API_KEY" \
  https://pingzen.dev/api/v1/monitors?workspace_id=1

How to find your workspace_id

The workspace_id field is required in the payload when creating monitors, alerts, reports, and status pages. There are two ways to get it.

Option 1: via UI (fastest). Open the workspaces page — each workspace card shows its ID. For most users it’s 1.

Option 2: via API (for CI/scripts). The /api/v1/workspaces* endpoints currently require JWT, not X-API-Key (see “Where X-API-Key works” above). Steps:

# 1. Log in — get an access_token
ACCESS=$(curl -sS -X POST https://pingzen.dev/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

# 2. Default workspace (the one pre-selected in the UI)
curl -sS -H "Authorization: Bearer $ACCESS" \
  https://pingzen.dev/api/v1/workspaces/default
# → {"id": 42, "name": "My Workspace", "is_default": true, ...}

# 3. Or a compact list of all (id, name) for dropdowns
curl -sS -H "Authorization: Bearer $ACCESS" \
  https://pingzen.dev/api/v1/workspaces/summary

One-liner “log in → fetch default id” for CI:

ACCESS=$(curl -sS -X POST https://pingzen.dev/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASS\"}" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')

WORKSPACE_ID=$(curl -sS -H "Authorization: Bearer $ACCESS" \
  https://pingzen.dev/api/v1/workspaces/default \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')

echo "$WORKSPACE_ID"   # → 42

Then plug $WORKSPACE_ID into the POST /api/v1/monitors payload below (that one is an X-API-Key endpoint).

Create a monitor

curl -X POST https://pingzen.dev/api/v1/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Site", "url": "https://example.com", "protocol": "https", "workspace_id": 1, "interval_seconds": 60}'

Get monitor

curl -H "X-API-Key: YOUR_API_KEY" \
  https://pingzen.dev/api/v1/monitors/123

Update monitor

curl -X PATCH https://pingzen.dev/api/v1/monitors/123 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 60, "name": "Updated Name"}'

Minimum interval_seconds depends on plan: FREE — 60s, paid — 30s. A value below the plan minimum returns 422 with a descriptive error.

Delete monitor

curl -X DELETE https://pingzen.dev/api/v1/monitors/123 \
  -H "X-API-Key: YOUR_API_KEY"

Create a heartbeat monitor

Create a heartbeat monitor for cron jobs and scheduled tasks. Returns a unique ping URL and secret. /heartbeats CRUD currently requires JWT (see “Where X-API-Key works”); workspace_id is passed as a query parameter, not in the body:

curl -X POST "https://pingzen.dev/api/v1/heartbeats?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $ACCESS" \
  -H "Content-Type: application/json" \
  -d '{"name": "Daily Backup", "expected_interval_seconds": 86400, "grace_period_seconds": 600}'

Send heartbeat ping (GET)

Simplest integration — just add to crontab or end of script. No authentication required.

# Simplest: chain with && so ping fires only on success
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG

# Or just a standalone ping
curl https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup

Heartbeat lifecycle signals

Report job lifecycle signals (start/success/fail) with optional payload and duration. Use X-Secret header for authentication.

# Report success with payload and duration
curl -X POST https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/success \
  -H "X-Secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 45000, "payload": {"rows": 500000}}'

# Report failure — triggers instant alert (no waiting for missed interval)
curl -X POST https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/fail \
  -H "X-Secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"error": "disk full"}}'

# One-liner for cron: success OR fail
/usr/local/bin/backup.sh \
  && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/success \
  || curl -fsS -m 10 https://pingzen.dev/api/v1/ping/aBcDeFgHiJkLmNoPqR/daily-backup/fail

Code Examples

Python Example

import requests

# Get your API key from: Profile → API Keys → Create New Key
PINGZEN_API_KEY = "YOUR_API_KEY"
BASE_URL = "https://pingzen.dev/api/v1"

headers = {
    "X-API-Key": PINGZEN_API_KEY,
    "Content-Type": "application/json"
}

# Create a monitor
monitor_data = {
    "name": "My Website",
    "url": "https://example.com",
    "protocol": "https",
    "interval_seconds": 60,
    "workspace_id": 1
}

response = requests.post(
    f"{BASE_URL}/monitors",
    headers=headers,
    json=monitor_data
)

print(response.json())

# Get all monitors (response is {monitors: [...], total, page, page_size})
data = requests.get(
    f"{BASE_URL}/monitors",
    headers=headers,
    params={"workspace_id": 1},  # scope to your workspace
).json()

for monitor in data["monitors"]:
    print(f"{monitor['name']}: {monitor['status']}")

JavaScript Example

// Get your API key from: Profile → API Keys → Create New Key
const PINGZEN_API_KEY = 'pz_abc12345_...';
const BASE_URL = 'https://pingzen.dev/api/v1';

const headers = {
  'X-API-Key': PINGZEN_API_KEY,
  'Content-Type': 'application/json'
};

// Create a monitor
async function createMonitor() {
  const response = await fetch(`${BASE_URL}/monitors`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
      name: 'My Website',
      url: 'https://example.com',
      protocol: 'https',
      interval_seconds: 60,
      workspace_id: 1
    })
  });

  const data = await response.json();
  console.log(data);
}

// Get all monitors (response is {monitors: [...], total, page, page_size})
async function getMonitors() {
  const response = await fetch(
    `${BASE_URL}/monitors?workspace_id=1`,  // scope to your workspace
    { headers: headers },
  );

  const data = await response.json();
  data.monitors.forEach(monitor => {
    console.log(`${monitor.name}: ${monitor.status}`);
  });
}

createMonitor();
getMonitors();

Heartbeat / Cron Monitoring Examples

Monitor cron jobs, scheduled tasks, and background processes. Create a heartbeat monitor, then send pings from your scripts to confirm they ran.

Bash / Cron Job

#!/bin/bash
# === Pattern 1: Chain with && (recommended for cron) ===
# curl runs ONLY if backup succeeds (exit code 0)
# If backup fails — no ping — PingZen alerts after grace period
#
# 0 2 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG

# === Pattern 2: Report both success AND failure (best) ===
# /success on success, /fail on failure — instant alert, no waiting
#
# 0 2 * * * /usr/local/bin/backup.sh \
#   && curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/success \
#   || curl -fsS -m 10 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/fail

# === Pattern 3: Full script with duration and payload ===
PING_KEY="YOUR_PING_KEY"
SLUG="daily-backup"
SECRET="YOUR_SECRET"
PING_URL="https://pingzen.dev/api/v1/ping/$PING_KEY/$SLUG"
SECONDS=0  # Bash built-in timer

# Your backup logic
pg_dump mydb > /backups/mydb_$(date +%F).sql

if [ $? -eq 0 ]; then
  # Report success with duration
  curl -fsS -m 10 -X POST "$PING_URL/success" \
    -H "X-Secret: $SECRET" \
    -H "Content-Type: application/json" \
    -d "{\"duration_ms\": $((SECONDS * 1000))}"
else
  # Report failure — instant alert
  curl -fsS -m 10 -X POST "$PING_URL/fail" \
    -H "X-Secret: $SECRET" \
    -H "Content-Type: application/json" \
    -d "{\"payload\": {\"error\": \"pg_dump failed\"}}"
fi

Python Heartbeat

import requests

BASE_URL = "https://pingzen.dev/api/v1"

# /heartbeats CRUD currently requires JWT (X-API-Key not yet supported).
# Log in once and reuse the token; refresh via /auth/refresh after 15 minutes.
login = requests.post(
    f"{BASE_URL}/auth/login",
    json={"email": "you@example.com", "password": "..."},
).json()
ACCESS = login["access_token"]
WORKSPACE_ID = requests.get(
    f"{BASE_URL}/workspaces/default",
    headers={"Authorization": f"Bearer {ACCESS}"},
).json()["id"]

# Create a heartbeat monitor (workspace_id goes in the query, not the body)
heartbeat = requests.post(
    f"{BASE_URL}/heartbeats",
    params={"workspace_id": WORKSPACE_ID},
    headers={"Authorization": f"Bearer {ACCESS}", "Content-Type": "application/json"},
    json={
        "name": "Daily Backup",
        "expected_interval_seconds": 86400,
        "grace_period_seconds": 600,
    },
).json()

ping_key = heartbeat["ping_key"]  # Workspace secret key
slug = heartbeat["slug"]
secret = heartbeat["secret"]      # Save this — shown only once!
ping_url = f"{BASE_URL}/ping/{ping_key}/{slug}"
print(f"Ping URL: {ping_url}")

# Send a ping at the end of your script (no auth needed for the ping itself,
# X-Secret authenticates lifecycle signals)
requests.post(
    f"{ping_url}/success",
    headers={"X-Secret": secret, "Content-Type": "application/json"},
    json={"duration_ms": 12000, "payload": {"status": "ok"}},
)

JavaScript Heartbeat

const BASE_URL = 'https://pingzen.dev/api/v1';

// /heartbeats CRUD currently requires JWT (X-API-Key not yet supported).
// Login once, reuse the token; refresh via /auth/refresh after 15 minutes.
async function login(email, password) {
  const res = await fetch(`${BASE_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  });
  return (await res.json()).access_token;
}

async function defaultWorkspaceId(access) {
  const res = await fetch(`${BASE_URL}/workspaces/default`, {
    headers: { 'Authorization': `Bearer ${access}` },
  });
  return (await res.json()).id;
}

// Create a heartbeat monitor (workspace_id goes in the query, not the body)
async function createHeartbeat(access, workspaceId) {
  const response = await fetch(
    `${BASE_URL}/heartbeats?workspace_id=${workspaceId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${access}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        name: 'Nightly Report',
        expected_interval_seconds: 86400,
        grace_period_seconds: 600,
      }),
    },
  );

  const data = await response.json();
  console.log('Ping URL:', `${BASE_URL}/ping/${data.ping_key}/${data.slug}`);
  console.log('Secret:', data.secret); // Save — shown only once!
  return data;
}

// Send heartbeat ping from your cron job (no JWT needed; X-Secret authenticates)
async function sendPing(pingKey, slug, secret) {
  await fetch(`${BASE_URL}/ping/${pingKey}/${slug}/success`, {
    method: 'POST',
    headers: {
      'X-Secret': secret,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      duration_ms: 5000,
      payload: { rows_processed: 1000 },
    }),
  });
}

OpenAPI & AI Agents

PingZen provides machine-readable specifications for AI agent integration and automation tools.

Rate Limits