API Reference
Full REST API Documentation
Automate monitor creation, retrieve real-time status, and integrate StatusPulse into your deployment pipelines. Every endpoint returns structured JSON.
Getting Started
Authentication
Every API request requires a valid bearer token. Generate yours from Settings → API Keys in your StatusPulse dashboard. Tokens are scoped to your workspace and expire after 365 days of inactivity.
Include your token in the Authorization header on every request. All endpoints are served over HTTPS at api.statuspulse.io/v1. Requests without a valid token return 401 Unauthorized.
Rate limits: 120 requests per minute on the Starter plan, 600 per minute on Business, and unlimited on Enterprise. Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.
curl -X GET https://api.statuspulse.io/v1/monitors \
-H "Authorization: Bearer sk_live_9f8e7d6c5b4a3210fedcba9876543210" \
-H "Content-Type: application/json"Core Resources
Endpoints
StatusPulse exposes a RESTful API organized around five core resources: monitors, checks, incidents, teams, and webhooks. Each resource supports standard CRUD operations.
GET
/v1/monitors
List all monitors in your workspace. Supports pagination via ?page= and ?per_page= (max 100). Filter by status with ?status=up|down|paused.
Response fields: id, name, url, type, interval_seconds, status, created_at, last_check_at, response_time_ms, ssl_expiry
POST
/v1/monitors
Create a new monitor. Required body fields: name, url, type (http | tls | ping | dns), and interval_seconds (30–3600). Optional: regions, tags, expected_status_codes.
Returns: 201 Created with the full monitor object and assigned monitor_id.
GET
/v1/monitors/:id/checks
Retrieve the last 50 check results for a specific monitor. Each check includes timestamp, response time, status code, body size, and the region that performed the probe.
Use case: Build uptime charts or feed data into Datadog, Grafana, or PagerDuty.
GET
/v1/incidents
List all incidents within a date range. Filter by ?monitor_id=, ?status=open|resolved, or ?severity=critical|warning. Includes start time, duration, affected checks, and resolution notes.
POST
/v1/webhooks
Register a webhook endpoint to receive real-time event payloads. Supported events: monitor.down, monitor.recovered, ssl.expiring_soon, incident.created. Each payload is signed with HMAC-SHA256.
PUT
/v1/monitors/:id
Update an existing monitor's configuration. You can change the URL, check interval, regions, tags, or pause/resume monitoring without deleting the resource.
Returns: 200 OK with the updated monitor object.
Code Samples
Examples
Copy-paste ready curl commands and JSON response schemas for the most common workflows.
Create an HTTP Monitor
curl -X POST https://api.statuspulse.io/v1/monitors \
-H "Authorization: Bearer sk_live_9f8e7d6c5b4a3210fedcba9876543210" \
-H "Content-Type: application/json" \
-d '{
"name": "checkout-api",
"url": "https://checkout.acmestore.io/api/v2/health",
"type": "http",
"interval_seconds": 60,
"regions": ["us-east-1", "eu-west-1", "ap-southeast-1"],
"expected_status_codes": [200],
"tags": ["production", "payments"]
}'Response (201 Created):
{
"id": "mon_8xK2pLq9rT4vNw",
"name": "checkout-api",
"url": "https://checkout.acmestore.io/api/v2/health",
"type": "http",
"interval_seconds": 60,
"status": "provisioning",
"regions": ["us-east-1", "eu-west-1", "ap-southeast-1"],
"tags": ["production", "payments"],
"expected_status_codes": [200],
"created_at": "2025-06-14T09:32:11Z",
"last_check_at": null,
"response_time_ms": null,
"ssl_expiry": "2026-03-22T00:00:00Z"
}List All Monitors (Paginated)
curl -X GET "https://api.statuspulse.io/v1/monitors?page=1&per_page=25&status=up" \
-H "Authorization: Bearer sk_live_9f8e7d6c5b4a3210fedcba9876543210"Response (200 OK):
{
"data": [
{
"id": "mon_8xK2pLq9rT4vNw",
"name": "checkout-api",
"url": "https://checkout.acmestore.io/api/v2/health",
"type": "http",
"interval_seconds": 60,
"status": "up",
"last_check_at": "2025-06-14T14:07:43Z",
"response_time_ms": 142,
"ssl_expiry": "2026-03-22T00:00:00Z"
},
{
"id": "mon_3jH7mRn2wQ5bYz",
"name": "web-app-tls",
"url": "app.acmestore.io",
"type": "tls",
"interval_seconds": 300,
"status": "up",
"last_check_at": "2025-06-14T14:05:00Z",
"response_time_ms": 38,
"ssl_expiry": "2026-01-08T00:00:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total": 14,
"total_pages": 1
}
}Register a Webhook
curl -X POST https://api.statuspulse.io/v1/webhooks \
-H "Authorization: Bearer sk_live_9f8e7d6c5b4a3210fedcba9876543210" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.acmestore.io/statuspulse",
"events": ["monitor.down", "monitor.recovered", "ssl.expiring_soon"],
"secret": "whsec_a1b2c3d4e5f6g7h8i9j0"
}'Webhook payload example (monitor.down event):
{
"event": "monitor.down",
"timestamp": "2025-06-14T14:12:07Z",
"webhook_id": "wh_4nM8pXq2rY6wKz",
"data": {
"monitor_id": "mon_8xK2pLq9rT4vNw",
"monitor_name": "checkout-api",
"status": "down",
"last_successful_check": "2025-06-14T14:07:43Z",
"failure_reason": "Connection timed out after 30000ms",
"region": "eu-west-1",
"consecutive_failures": 3
}
}All webhook payloads are signed using HMAC-SHA256 with your secret. Verify the signature from the X-StatusPulse-Signature header before processing events.