REST API v1

API Reference

The WatchPing REST API lets you manage monitors, retrieve status data, and integrate uptime monitoring into your own tools and workflows.

Base URL

https://www.watchping.io/api/v1

Auth Header

X-API-Key: your_key

⚠️ API access requires a Starter plan or higher. Get your key from Dashboard → Settings.

Authentication

All requests must include your API key in the X-API-Key header.

bash

curl -H "X-API-Key: your_key" https://www.watchping.io/api/v1/monitors

If the key is missing or invalid, you'll receive a 401 Unauthorized response.

json

{
  "error": "Unauthorized",
  "message": "Missing or invalid X-API-Key"
}

Endpoints

All responses are JSON. All requests should use Content-Type: application/json for POST/PUT.

GET/monitorsList all monitors

Response

json

{
  "monitors": [
    {
      "id": "mon_abc123",
      "name": "My Website",
      "url": "https://example.com",
      "type": "http",
      "interval": 60,
      "status": "up",
      "uptime_30d": 99.97
    }
  ]
}

GET/monitors/:idGet a single monitor

Response

json

{
  "id": "mon_abc123",
  "name": "My Website",
  "url": "https://example.com",
  "type": "http",
  "interval": 60,
  "status": "up",
  "created_at": "2024-01-15T10:30:00Z",
  "uptime_30d": 99.97,
  "response_time_ms": 142
}

POST/monitorsCreate a new monitor

Request body

json

{
  "name": "My API",
  "url": "https://api.example.com/health",
  "type": "http",
  "interval": 60,
  "alert_email": true,
  "alert_whatsapp": false
}

Response

json

{
  "id": "mon_xyz789",
  "name": "My API",
  "url": "https://api.example.com/health",
  "status": "pending",
  "created_at": "2024-07-01T12:00:00Z"
}

DELETE/monitors/:idDelete a monitor

Response

json

{
  "success": true,
  "message": "Monitor deleted"
}

GET/statusAccount status summary

Response

json

{
  "plan": "pro",
  "monitors_used": 12,
  "monitors_limit": 50,
  "checks_today": 17280,
  "uptime_overall": 99.95
}

Code Examples

Complete examples showing how to authenticate and manage monitors.

javascript

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://www.watchping.io/api/v1';

// List all monitors
const res = await fetch(`${BASE_URL}/monitors`, {
  headers: { 'X-API-Key': API_KEY }
});
const { monitors } = await res.json();
console.log(monitors);

// Create a monitor
const newMonitor = await fetch(`${BASE_URL}/monitors`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Website',
    url: 'https://example.com',
    type: 'http',
    interval: 60
  })
});
const created = await newMonitor.json();
console.log('Created:', created.id);

Error Codes

The API uses standard HTTP status codes.

Code	Status	Description
`200`	OK	Request succeeded
`401`	Unauthorized	Missing or invalid X-API-Key header
`404`	Not Found	Monitor ID does not exist or belongs to another account
`429`	Too Many Requests	Rate limit exceeded — slow down and retry after 1 hour
`500`	Internal Server Error	Something went wrong on our end — contact support

Rate Limits

To ensure fair usage, the API is rate-limited per API key.

100

requests per hour

429

status when exceeded

1 hr

window resets after

When rate limited, the response will be:

json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 1 hour.",
  "retry_after": 3600
}

Need higher limits?

Enterprise rate limits are available. Contact us for custom plans.