API Documentation

The PingBase API is a REST API that lets you manage monitors, retrieve check results, and configure your status page programmatically.

Authentication

PingBase supports two authentication methods: JWT tokens (for interactive use) and API keys (for CI, scripts, and integrations). Both use the same Authorization: Bearer header.

# Get a token via login
curl -X POST https://pingba-se-worker.pingbase.workers.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"yourpassword"}'

# Use the token
Authorization: Bearer eyJ...

# Create an API key in Dashboard → API Keys
# Keys look like: pb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Use the key exactly like a JWT token
Authorization: Bearer pb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Or via environment variable (for CLI and integrations)
export PINGBASE_API_KEY=pb_live_...

Requests without a valid token to authenticated endpoints return 401 Unauthorized.

Errors

All errors return a JSON body with an error field.

{ "error": "Invalid email or password (min 8 chars)" }

Auth

{
  "email": "you@example.com",
  "password": "minlength8"
}

{
  "token": "eyJ...",
  "plan": "free",
  "statusPageSlug": "you-a1b2c3"
}

curl -X POST https://pingba-se-worker.pingbase.workers.dev/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"mypassword"}'

{
  "email": "you@example.com",
  "password": "mypassword"
}

{
  "token": "eyJ...",
  "plan": "free"
}

curl -X POST https://pingba-se-worker.pingbase.workers.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"mypassword"}'

User

Returns your account details including current plan.

{
  "id": "uuid",
  "email": "you@example.com",
  "plan": "free",
  "created_at": 1712345678
}

curl https://pingba-se-worker.pingbase.workers.dev/api/me \
  -H "Authorization: Bearer $TOKEN"

Monitors

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "name": "My API",
    "url": "https://api.example.com/health",
    "interval_minutes": 5,
    "is_active": 1,
    "status": "up",
    "last_checked_at": 1712345678,
    "created_at": 1712345000
  }
]

curl https://pingba-se-worker.pingbase.workers.dev/api/monitors \
  -H "Authorization: Bearer $TOKEN"

{
  "name": "My API",
  "url": "https://api.example.com/health"
}

{
  "id": "uuid",
  "user_id": "uuid",
  "name": "My API",
  "url": "https://api.example.com/health",
  "interval_minutes": 5,
  "is_active": 1,
  "status": "pending",
  "last_checked_at": null,
  "created_at": 1712345678
}

curl -X POST https://pingba-se-worker.pingbase.workers.dev/api/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My API","url":"https://api.example.com/health"}'

{ "success": true }

curl -X DELETE \
  https://pingba-se-worker.pingbase.workers.dev/api/monitors/MONITOR_ID \
  -H "Authorization: Bearer $TOKEN"

Check Results

Returns the last 100 check results for a monitor, newest first.

[
  {
    "id": "uuid",
    "monitor_id": "uuid",
    "status": "up",
    "response_time_ms": 142,
    "status_code": 200,
    "error": null,
    "checked_at": 1712345678
  },
  {
    "id": "uuid",
    "monitor_id": "uuid",
    "status": "down",
    "response_time_ms": null,
    "status_code": null,
    "error": "Connection timeout",
    "checked_at": 1712345378
  }
]

curl https://pingba-se-worker.pingbase.workers.dev/api/monitors/MONITOR_ID \
  -H "Authorization: Bearer $TOKEN"

Status Page

{
  "id": "uuid",
  "user_id": "uuid",
  "slug": "you-a1b2c3",
  "title": "My Status Page",
  "description": null,
  "created_at": 1712345000
}

curl https://pingba-se-worker.pingbase.workers.dev/api/status-page \
  -H "Authorization: Bearer $TOKEN"

{
  "monitor_id": "uuid"
}

{ "success": true }

curl -X POST \
  https://pingba-se-worker.pingbase.workers.dev/api/status-page/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"monitor_id":"MONITOR_ID"}'

{
  "title": "Acme Corp Status",
  "description": null,
  "overall_status": "operational",
  "monitors": [
    {
      "id": "uuid",
      "name": "Main Website",
      "url": "https://acme.com",
      "status": "up",
      "last_checked_at": 1712345678,
      "uptime_pct": "99.98",
      "incidents": []
    }
  ]
}

curl https://pingba-se-worker.pingbase.workers.dev/api/status/your-slug

Heartbeat

Heartbeat monitors watch your cron jobs and background tasks. Each heartbeat monitor has a unique token. Your job pings the URL on schedule — if PingBase doesn't receive a ping within the expected interval, it alerts you.

Send a ping for a heartbeat monitor. Also accepts POST and HEAD. Get the token from the dashboard (expand a heartbeat monitor → Copy Ping URL).

curl https://pingba-se-worker.pingbase.workers.dev/api/heartbeat/YOUR_HEARTBEAT_TOKEN

{ "ok": true }

# In crontab or CI — run your job, then ping PingBase
0 3 * * * /usr/bin/backup.sh && curl -s https://pingba-se-worker.pingbase.workers.dev/api/heartbeat/YOUR_TOKEN

API Keys

API keys are permanent tokens for use in CI/CD, scripts, and integrations. They work as drop-in replacements for JWT tokens — use them in the Authorization: Bearer header or as the PINGBASE_API_KEY environment variable for the CLI and MCP server.

[
  {
    "id": "uuid",
    "name": "CI pipeline",
    "created_at": 1712345678
  }
]

curl https://pingba-se-worker.pingbase.workers.dev/api/api-keys \
  -H "Authorization: Bearer $TOKEN"

{ "name": "CI pipeline" }

{
  "id": "uuid",
  "name": "CI pipeline",
  "key": "pb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": 1712345678
}

curl -X DELETE \
  https://pingba-se-worker.pingbase.workers.dev/api/api-keys/KEY_ID \
  -H "Authorization: Bearer $TOKEN"

Health

Returns worker status. Use this to verify the API is reachable.

{ "ok": true, "ts": 1712345678000 }

curl https://pingba-se-worker.pingbase.workers.dev/api/health

CLI

The pingbase-cli lets you manage monitors, check status, and list incidents from your terminal.

npm install -g pingbase-cli

# Create an API key in Dashboard → API Keys, then:
export PINGBASE_API_KEY=pb_live_...

# List all monitors
pingbase monitors

# Add an HTTP monitor
pingbase add "My API" https://api.example.com

# Add a heartbeat monitor (for cron jobs)
pingbase add "Nightly Backup" --type heartbeat --interval 1440

# View recent checks for a monitor
pingbase status <monitor-id>

# Delete a monitor
pingbase delete <monitor-id>

# List active incidents
pingbase incidents

# Manage API keys
pingbase keys list
pingbase keys create "CI pipeline"
pingbase keys revoke <key-id>

MCP Server (AI)

The pingbase-mcp package exposes PingBase as an MCP (Model Context Protocol) server, letting Claude Code and other AI assistants manage your monitors via natural language.

npm install -g pingbase-mcp

{
  "mcpServers": {
    "pingbase": {
      "command": "pingbase-mcp",
      "env": {
        "PINGBASE_API_KEY": "pb_live_..."
      }
    }
  }
}

GitHub Action

The PingBase GitHub Action checks your monitor status in CI/CD workflows. Use it to gate deployments, verify production health after a deploy, or block PRs when monitors are down.

# 1. Create an API key: Dashboard → API Keys
# 2. Add it as a GitHub secret: Settings → Secrets → PINGBASE_API_KEY

- name: Check uptime monitors
  uses: pingbase/check-monitors@v1
  with:
    api-key: ${{ secrets.PINGBASE_API_KEY }}

- name: Deploy
  run: npm run deploy

- name: Verify production health
  uses: pingbase/check-monitors@v1
  with:
    api-key: ${{ secrets.PINGBASE_API_KEY }}
    fail-on-down: 'true'

- name: Check production API monitor
  uses: pingbase/check-monitors@v1
  with:
    api-key: ${{ secrets.PINGBASE_API_KEY }}
    monitor-id: your-monitor-id
    fail-on-down: 'true'