REST API

Quick start

1. In the app, open Settings → API keys and create a key. Copy it: it's shown only once.
2. Send it as a Bearer token:

curl https://pingrobot.io/api/v1/monitors \
  -H "Authorization: Bearer pr_live_…"

Create a monitor:

curl https://pingrobot.io/api/v1/monitors \
  -H "Authorization: Bearer pr_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "type": "http", "name": "Shop", "url": "https://shop.example.com" }'

OpenAPI and MCP

• OpenAPI 3.1: pingrobot.io/api/v1/openapi.json describes every route below. Import it into Postman, Insomnia or Bruno, or generate a client with your favourite OpenAPI generator. It doesn't need a key.
• MCP server: connect Claude, Cursor or VS Code at https://pingrobot.io/mcp with the same keys. See the MCP docs.

Basics

Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer pr_live_9f2c…

Each key has an access level, chosen when you create it. Keys work on your account: the same monitors and pages you see in the app.

We store only a hash of each key, so a lost key can't be shown again: revoke it in Settings and create a new one. Revoking takes effect at once. You can have up to 10 keys. Keep keys on your server; they are not meant for code that runs in a browser.

A key can't reach billing, account settings or other keys. Those need a signed-in session in the app.

Errors

Errors return a JSON body with a human-readable message. Plan limits also say "upgrade": true:

{ "error": "Your plan includes 10 monitors. Upgrade to add more.", "upgrade": true }

Account

GET /account

Your plan, its limits and what you use. Handy to check a key works.

{
  "mode": "live",
  "email": "you@example.com",
  "plan": "pro",
  "limits": { "monitors": 50, "minInterval": 1, "statusPages": 5, "channels": ["email", "webhook", "slack", "discord"], "historyDays": 365 },
  "usage": { "monitors": 12, "statusPages": 1 },
  "grace": null
}

Monitors

To pause a monitor send PATCH with { "active": false }, and { "active": true } to resume it.

Monitor fields

Read-only fields in responses: id, status (pending, up, down or paused), statusSince, lastReason, heartbeatUrl and lastPingAt (heartbeats), createdAt, and ssl / domain with the dates we found.

Example: an API monitor with a JSON rule

curl https://pingrobot.io/api/v1/monitors \
  -H "Authorization: Bearer pr_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "name": "API health",
    "url": "https://api.example.com/health",
    "intervalMin": 1,
    "httpAuth": { "type": "bearer", "token": "YOUR_SERVICE_TOKEN" },
    "jsonRules": [{ "path": "$.status", "op": "equals", "value": "ok" }],
    "alertAfterMin": 2
  }'

Example: a heartbeat for a cron job

curl https://pingrobot.io/api/v1/monitors \
  -H "Authorization: Bearer pr_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "type": "heartbeat", "name": "Nightly backup", "intervalMin": 1440 }'

The response's heartbeatUrl is the address your job calls when it finishes, for example curl -fsS https://pingrobot.io/hb/…. Calling it doesn't need an API key.

Example: pause monitors during a deploy

curl -X PATCH https://pingrobot.io/api/v1/monitors/12 \
  -H "Authorization: Bearer pr_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

For planned work that repeats, a maintenance window is usually better: checks pause and resume on their own.

POST /monitors/test

Send the same fields as for a new monitor. We run one check now and return the result and the first part of the response, without saving anything. It is limited to 10 tests a minute.

Alert contacts

A new confirmed contact is added to all your monitors. To choose per monitor, set contactIds on the monitor. Webhook payloads and signatures are described in the webhook docs.

Maintenance windows

While a window is active, the monitors it covers aren't checked and send no alerts.

# Every Sunday 02:00–03:00 Istanbul time, all monitors
curl https://pingrobot.io/api/v1/maintenance \
  -H "Authorization: Bearer pr_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Weekly patching", "repeat": "weekly", "days": 64, "timeMin": 120, "durationMin": 60, "tz": "Europe/Istanbul", "monitorIds": null }'

A deploy script can open a one-off window right before it starts (startAt now, endAt in 15 minutes) and delete it when it's done.

Status pages

The page is public at https://pingrobot.io/s/{slug} and https://{slug}.pingrobot.io. Custom domains are set up in the app (see status page domains).

Announcements

kind and its status values: incident (investigating, identified, monitoring, resolved), maintenance (scheduled, in_progress, completed) and info (posted). With "notify": true (Pro), confirmed email subscribers get the update.

Changes

We add fields and routes without notice, so ignore fields you don't know. Anything that would break an existing integration comes as a new version (/api/v2), and v1 keeps working.

Questions or something missing? Get in touch.