API Reference

GET

/checks

Retrieve a paginated list of all uptime checks in your account. Supports filtering by status (active, paused, archived), type (http, ping, dns, ssl), and tags. Returns up to 100 checks per page with cursor-based pagination.

POST

/checks

Create a new uptime check. Required fields: name, type, target, and interval_seconds (30–3600). Optional fields include regions, tags, expected_status_codes, follow_redirects, and notification channel IDs. Returns the created check object with a unique check_id.

GET

/checks/{check_id}/history

Fetch historical probe results for a specific check. Query parameters: start and end (ISO 8601 timestamps), resolution (1m, 5m, 1h, 1d), and region. Returns an array of probe events with response time, status code, and availability percentage.

GET

/incidents

List all downtime incidents. Filter by date range, severity (critical, warning), and resolution state. Each incident includes started_at, resolved_at, duration_seconds, affected check IDs, and root-cause notes if manually annotated.

GET

/metrics/availability

Aggregate availability metrics across your account or per check. Parameters: period (24h, 7d, 30d, 90d), group_by (check, region, tag). Returns uptime percentages, mean response time, and p95/p99 latency percentiles.

POST

/webhooks

Register a webhook endpoint for real-time event delivery. Payload includes event type (check.down, check.up, check.slow, ssl.expiring), check metadata, and a signing_secret for HMAC-SHA256 verification. SitePulse retries failed deliveries with exponential backoff up to 5 attempts.

Create an HTTP Check

curl -X POST https://api.sitepulse.io/v2/checks \
-H "Authorization: Bearer sk_live_7xK9mP2nQ4wR8vL" \
-H "Content-Type: application/json" \
-d '{"name":"shop.example.com","type":"http","target":"https://shop.example.com","interval_seconds":60,"regions":["us-east","eu-west","ap-southeast"],"expected_status_codes":[200],"tags":["production","ecommerce"]}'

Response (201 Created):
{"check_id":"chk_8f3a1b9c","name":"shop.example.com","status":"active","created_at":"2025-01-14T09:23:11Z"}

Query Availability Metrics

curl "https://api.sitepulse.io/v2/metrics/availability?period=30d&group_by=check" \
-H "Authorization: Bearer sk_live_7xK9mP2nQ4wR8vL"

Response (200 OK):
{"period":"2024-12-15/2025-01-14","checks":[{"check_id":"chk_8f3a1b9c","availability_pct":99.97,"mean_response_ms":142,"p95_response_ms":310,"p99_response_ms":485},{"check_id":"chk_2d7e0f1a","availability_pct":99.99,"mean_response_ms":89,"p95_response_ms":175,"p99_response_ms":240}]}

Fetch Recent Incidents

curl "https://api.sitepulse.io/v2/incidents?severity=critical&resolved=false" \
-H "Authorization: Bearer sk_live_7xK9mP2nQ4wR8vL"

Response (200 OK):
{"incidents":[{"incident_id":"inc_4b2c8d1e","check_id":"chk_2d7e0f1a","started_at":"2025-01-14T14:02:33Z","duration_seconds":1247,"severity":"critical","resolved":false,"affected_regions":["eu-west"]}],"total":1}

Free Plan

100 requests / minute across all endpoints. Burst allowance of 20 requests. Read-only endpoints (/checks, /metrics, /incidents) share the same pool. Write operations (POST /checks, POST /webhooks) count double. Exceeding the limit returns 429 Too Many Requests with a Retry-After header in seconds.

Pro Plan

1,000 requests / minute. Burst allowance of 100 requests. Separate pools for read (2,000/min) and write (500/min) operations. Webhook delivery does not count against your API rate limit. Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for proactive monitoring.

Enterprise Plan

10,000 requests / minute with configurable limits per API key. Dedicated rate-limit pool for bulk history exports. Contact api-support@sitepulse.io to request custom limits. Includes priority queue processing for webhook deliveries and bulk metric queries exceeding 90-day windows.