docs/api reference

api reference

pro

available on pro plan only.

authentication

include your api key in the authorization header on every request.

bash

curl https://ping-guard.com/api/monitors \
  -H "Authorization: Bearer YOUR_API_KEY"

you can find your api key in account settings → api.

note: api key management is coming soon. the endpoints below are already available and will require a key once the feature ships.

base url

https://ping-guard.com/api

all responses are json. all request bodies must be json with Content-Type: application/json.

endpoints

GET/api/monitorslist all your monitors

bash

curl https://ping-guard.com/api/monitors \
  -H "Authorization: Bearer YOUR_API_KEY"

response

json

{
  "monitors": [
    {
      "id": "monitor_abc123",
      "name": "daily-backup",
      "slug": "daily-backup-x7f2k",
      "interval_seconds": 3600,
      "grace_seconds": 300,
      "status": "up",
      "last_ping_at": "2024-01-15T14:01:22Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST/api/monitorscreate a monitor

bash

curl -X POST https://ping-guard.com/api/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-report",
    "interval_seconds": 604800,
    "grace_seconds": 600
  }'

response — 201 created

json

{
  "monitor": {
    "id": "monitor_xyz789",
    "name": "weekly-report",
    "slug": "weekly-report-m3n9p",
    "ping_url": "https://ping-guard.com/p/weekly-report-m3n9p",
    "interval_seconds": 604800,
    "grace_seconds": 600,
    "status": "new",
    "created_at": "2024-01-15T14:00:00Z"
  }
}

GET/api/monitors/:idget monitor detail

bash

curl https://ping-guard.com/api/monitors/monitor_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

PATCH/api/monitors/:idupdate a monitor

bash

curl -X PATCH https://ping-guard.com/api/monitors/monitor_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-backup-v2",
    "grace_seconds": 600
  }'

DELETE/api/monitors/:iddelete a monitor

bash

curl -X DELETE https://ping-guard.com/api/monitors/monitor_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

returns 204 no content on success.

GET/api/monitors/:id/pingsget ping history

bash

curl https://ping-guard.com/api/monitors/monitor_abc123/pings \
  -H "Authorization: Bearer YOUR_API_KEY"

response

json

{
  "pings": [
    {
      "id": "ping_001",
      "received_at": "2024-01-15T14:01:22Z",
      "status": "ok",
      "duration_ms": 45
    },
    {
      "id": "ping_000",
      "received_at": null,
      "status": "missed",
      "expected_at": "2024-01-14T14:00:00Z"
    }
  ],
  "total": 30,
  "page": 1
}

error codes

400bad request — invalid json or missing required fields

401unauthorized — missing or invalid api key

403forbidden — feature not available on your plan

404not found — monitor does not exist

429too many requests — rate limit exceeded (60 req/min)

500server error — try again in a few seconds

← alert channels next: faq →