API

API Reference

Base URL: https://deadping.io/api. All endpoints return JSON. Authenticated endpoints require a session cookie or X-API-Key header.

The DeadPing REST API provides full programmatic access to monitors, pings, incidents, status pages, and API keys. All endpoints require an API key passed in the Authorization header. Responses use JSON format with standard HTTP status codes for error handling.

Authentication

Most endpoints require authentication. DeadPing supports two methods:

1. Session Cookies

When using the dashboard in a browser, authentication is handled automatically via Supabase session cookies. No extra headers needed.

2. API Key

For programmatic access, pass your API key in the X-API-Key header. Keys use the format dp_live_... and can be created from the dashboard Settings page.

bash

curl -H "X-API-Key: dp_live_abc123..." https://deadping.io/api/monitors

Only the key hash is stored server-side. The plaintext key is shown once at creation and cannot be retrieved later.

Error Responses

All errors return a JSON object with an error field and an appropriate HTTP status code.

json

{ "error": "Monitor not found" }

Status Codes

400 – Bad request (missing or invalid parameters)
401 – Unauthorized (missing or invalid authentication)
403 – Forbidden (feature not available on your plan)
404 – Resource not found
429 – Rate limited (too many requests)
500 – Internal server error

Ping (Public)

GET | POST | HEAD /api/ping/:token

Records a heartbeat for the monitor identified by :token. No authentication required. Rate limited to one ping per 5 seconds per monitor.

Simple Ping (GET / HEAD)

A GET or HEAD request records that the job ran successfully. No request body needed.

bash

# Simple ping
curl -fsS https://deadping.io/api/ping/YOUR_TOKEN

# With retries (recommended for production)
curl -fsS --retry 3 --max-time 10 https://deadping.io/api/ping/YOUR_TOKEN

Ping with Output (POST)

Send stdout/stderr in the request body to capture job output. Output size is gated by plan: Free = 1 KB, Pro = 100 KB, Business = 1 MB. Larger bodies are truncated.

bash

# Capture cron output
my-backup-script.sh 2>&1 | curl -fsS -X POST \
  --data-binary @- \
  https://deadping.io/api/ping/YOUR_TOKEN

Query Parameters

exit_code (number) – Process exit code (0 = success)
duration_ms (number) – How long the job took in milliseconds
progress (number) – Current progress value (e.g. 45)
total (number) – Total expected value (e.g. 100)
message (string) – Progress status message
status (string) – Set to "in_progress" to indicate the job is still running

bash

# Report exit code and duration
curl -fsS "https://deadping.io/api/ping/YOUR_TOKEN?exit_code=0&duration_ms=4523"

# Report progress mid-job
curl -fsS "https://deadping.io/api/ping/YOUR_TOKEN?status=in_progress&progress=45&total=100&message=Processing+batch+3"

# Final ping when complete
curl -fsS "https://deadping.io/api/ping/YOUR_TOKEN?progress=100&total=100&exit_code=0"

Response:

json

{ "ok": true }

Monitors

All monitor endpoints require authentication via session cookie or X-API-Key header.

List Monitors

GET /api/monitors

bash

curl -H "X-API-Key: dp_live_..." https://deadping.io/api/monitors

Returns an array of all monitors for your account, including id, name, status, ping_token, last_ping_at, next_expected_at, and schedule config.

json

[
  {
    "id": "uuid",
    "name": "nightly-backup",
    "status": "up",
    "ping_token": "abc123",
    "last_ping_at": "2026-03-08T02:01:00Z",
    "next_expected_at": "2026-03-09T02:05:00Z",
    "expected_interval_seconds": 86400,
    "grace_period_seconds": 300,
    "cron_expression": "0 2 * * *",
    "paused": false
  }
]

Create Monitor

POST /api/monitors

bash

curl -X POST https://deadping.io/api/monitors \
  -H "X-API-Key: dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-backup",
    "expected_interval_seconds": 86400,
    "grace_period_seconds": 300,
    "cron_expression": "0 2 * * *"
  }'

Required Fields

name: Display name for the monitor
expected_interval_seconds: How often the ping should arrive (e.g. 86400 for daily)

Optional Fields

grace_period_seconds: Extra time before alerting (default: 60)
cron_expression: Standard 5-field cron expression for precise scheduling

Returns the created monitor object including ping_token for constructing the ping URL.

Get Monitor

GET /api/monitors/:id

bash

curl -H "X-API-Key: dp_live_..." https://deadping.io/api/monitors/MONITOR_ID

Returns the full monitor object including recent ping history and alert configuration.

Update Monitor

PATCH /api/monitors/:id

bash

curl -X PATCH https://deadping.io/api/monitors/MONITOR_ID \
  -H "X-API-Key: dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "weekly-backup", "paused": false }'

Updatable fields: name, expected_interval_seconds, grace_period_seconds, cron_expression, paused.

Delete Monitor

DELETE /api/monitors/:id

bash

curl -X DELETE https://deadping.io/api/monitors/MONITOR_ID \
  -H "X-API-Key: dp_live_..."

Permanently deletes the monitor and all associated ping history. This action cannot be undone.

Bulk Import

POST /api/monitors/import

Import monitors in bulk from crontab files or Kubernetes CronJob YAML manifests. The endpoint parses the content, extracts job definitions, and creates monitors for each one.

bash

curl -X POST https://deadping.io/api/monitors/import \
  -H "X-API-Key: dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "format": "crontab",
    "content": "0 2 * * * /usr/local/bin/backup.sh\n*/5 * * * * /usr/local/bin/healthcheck.sh"
  }'

Body Fields

format (required) – "crontab" or "k8s"
content (required) – The raw file content to parse
selected (optional) – Array of job names/commands to import. If omitted, all parsed jobs are imported.

Pings

Endpoints for querying recorded ping data. Requires authentication.

Search Ping Output

GET /api/pings/search

Full-text search across captured ping output (stdout/stderr). Requires Pro plan or higher. Rate limited to 30 requests per minute.

bash

curl -G https://deadping.io/api/pings/search \
  -H "X-API-Key: dp_live_..." \
  --data-urlencode "q=error" \
  --data-urlencode "monitor_id=MONITOR_ID" \
  --data-urlencode "limit=20"

Query Parameters

q (required) – Search query string
monitor_id (optional) – Filter results to a specific monitor
limit (optional) – Maximum results to return (default: 50, max: 100)

json

[
  {
    "id": "uuid",
    "monitor_id": "uuid",
    "received_at": "2026-03-08T02:01:00Z",
    "body": "...matching output excerpt...",
    "exit_code": 1,
    "duration_ms": 4523
  }
]

Incidents

Incident management for grouped alerts. Requires authentication and Business plan.

List Incidents

GET /api/incidents

bash

# List all incidents
curl -H "X-API-Key: dp_live_..." https://deadping.io/api/incidents

# Filter by status
curl -H "X-API-Key: dp_live_..." "https://deadping.io/api/incidents?status=open"

Query Parameters

status (optional) – Filter by open or resolved

Get Incident

GET /api/incidents/:id

bash

curl -H "X-API-Key: dp_live_..." https://deadping.io/api/incidents/INCIDENT_ID

Returns the full incident object including affected monitors, alert history, and postmortem fields.

json

{
  "id": "uuid",
  "status": "open",
  "started_at": "2026-03-08T02:05:00Z",
  "resolved_at": null,
  "affected_monitors": [
    { "id": "uuid", "name": "nightly-backup", "status": "down" }
  ],
  "alerts": [
    { "channel": "slack", "sent_at": "2026-03-08T02:06:00Z" }
  ],
  "root_cause": null,
  "action_items": null
}

Update Incident Postmortem

PATCH /api/incidents/:id

bash

curl -X PATCH https://deadping.io/api/incidents/INCIDENT_ID \
  -H "X-API-Key: dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "root_cause": "Database connection pool exhausted",
    "action_items": "Increase pool size to 50, add connection timeout monitoring"
  }'

Body Fields

root_cause (optional) – Root cause description
action_items (optional) – Follow-up actions to prevent recurrence

Status Pages

Public-facing status pages for your monitors. Requires authentication. Plan limits: Free = 1 page, Pro = 5 pages, Business = 10 pages.

List Status Pages

GET /api/status-pages

bash

curl -H "X-API-Key: dp_live_..." https://deadping.io/api/status-pages

Create Status Page

POST /api/status-pages

bash

curl -X POST https://deadping.io/api/status-pages \
  -H "X-API-Key: dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme Corp Status",
    "slug": "acme-status",
    "monitor_ids": ["uuid-1", "uuid-2"]
  }'

Get Status Page

GET /api/status-pages/:id

bash

curl -H "X-API-Key: dp_live_..." https://deadping.io/api/status-pages/STATUS_PAGE_ID

Update Status Page

PATCH /api/status-pages/:id

bash

curl -X PATCH https://deadping.io/api/status-pages/STATUS_PAGE_ID \
  -H "X-API-Key: dp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Status Page" }'

Delete Status Page

DELETE /api/status-pages/:id

bash

curl -X DELETE https://deadping.io/api/status-pages/STATUS_PAGE_ID \
  -H "X-API-Key: dp_live_..."

API Keys

Manage programmatic API keys. These endpoints require session authentication (browser only) – you cannot use an API key to manage other API keys. Maximum 5 keys per account.

List API Keys

GET /api/keys

bash

curl -H "Cookie: ..." https://deadping.io/api/keys

Returns key metadata (id, name, prefix, created date). The full key value is never returned after creation.

json

[
  {
    "id": "uuid",
    "name": "CI/CD Pipeline",
    "prefix": "dp_live_abc1",
    "created_at": "2026-03-01T00:00:00Z"
  }
]

Create API Key

POST /api/keys

bash

curl -X POST https://deadping.io/api/keys \
  -H "Cookie: ..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI/CD Pipeline" }'

Returns the full API key once. Copy it immediately – only the hash is stored and the plaintext cannot be retrieved later.

json

{
  "id": "uuid",
  "name": "CI/CD Pipeline",
  "key": "dp_live_abc123def456..."
}

Delete API Key

DELETE /api/keys/:id

bash

curl -X DELETE https://deadping.io/api/keys/KEY_ID \
  -H "Cookie: ..."

Immediately revokes the key. Any requests using this key will receive a 401 response.

MCP Server

POST /api/mcp

Model Context Protocol endpoint for AI agent integrations (Claude, Cursor, Windsurf, etc.). Authenticate with your API key via the X-API-Key header.

Available Tools

list_monitors – List all monitors
get_monitor – Get monitor details by ID
create_monitor – Create a new monitor
pause_monitor – Pause a monitor
resume_monitor – Resume a paused monitor
delete_monitor – Delete a monitor
list_incidents – List incidents
get_incident – Get incident details
update_incident – Update incident postmortem
search_output – Search ping output (Pro+)
get_status – Get overall system status

json

// MCP server configuration for Claude Desktop / Cursor
{
  "mcpServers": {
    "deadping": {
      "url": "https://deadping.io/api/mcp",
      "headers": {
        "X-API-Key": "dp_live_..."
      }
    }
  }
}

Health Check

GET /api/health

Public endpoint. Returns service status and database connectivity. Use this to monitor DeadPing itself.

json

{ "ok": true, "timestamp": "2026-03-08T...", "db": "connected" }