API Reference — REST API

Retrieve a paginated list of all monitors belonging to the authenticated team. Supports query parameters ?page, ?limit (max 100), and ?status=up|down|paused for filtering.

Create a new monitor. Required body fields: name (string, 2–128 chars), url (valid HTTP(S) URL), interval_seconds (30, 60, 120, or 300). Optional: tags (array of strings), regions (array, default ["eu-central-1","us-east-1","ap-northeast-1"]), expected_status (integer, default 200).

Fetch full details for a single monitor by its UUID. Returns configuration, current status, last check timestamp, and SLA summary for the past 30 days.

Update an existing monitor. Only provided fields are patched — omit fields you don't want to change. Changing interval_seconds takes effect on the next scheduled check.

Permanently delete a monitor and all associated check logs. This action is irreversible. Returns 204 No Content on success.

Return the real-time status of a monitor: up, down, or degraded. Includes last_check_at (ISO 8601), response_time_ms, and uptime_30d (percentage). Ideal for dashboard widgets.

Retrieve check history for a monitor. Paginated results with ?page and ?limit. Optional filter ?from and ?to (ISO 8601 timestamps). Each log entry contains timestamp, region, status_code, response_time_ms, and error_message (nullable).

List all incidents across the team's monitors. Supports ?monitor_id and ?resolved=true|false filters. Each incident includes id, monitor_id, started_at, resolved_at (nullable), duration_seconds, and affected_regions.

Manually create an incident record. Body requires monitor_id and title. Optional: description (Markdown supported). Useful for logging maintenance windows or known issues.

Register a new webhook endpoint. Body requires url, events (array: "status_change", "incident_created", "sla_breach"), and secret (HMAC-SHA256 signing key). Returns webhook_id and verification_token.

List all registered webhooks for the team. Each entry includes id, url, events, active (boolean), and last_triggered_at. Supports ?active=true|false filtering.

curl -X POST https://api.statuspool.io/v1/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API — api.example.com",
    "url": "https://api.example.com/health",
    "interval_seconds": 60,
    "expected_status": 200,
    "regions": ["eu-central-1", "us-east-1", "ap-northeast-1"],
    "tags": ["production", "api-gateway"]
  }'

curl -s https://api.statuspool.io/v1/monitors/4f2a8c1e-9b3d-47e1-aa5f-0d6c8e21b907/status \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "status": "up",
#   "last_check_at": "2025-01-15T09:42:11Z",
#   "response_time_ms": 143,
#   "uptime_30d": 99.972
# }

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
resp = requests.get(
    "https://api.statuspool.io/v1/monitors",
    headers=headers,
    params={"page": 1, "limit": 50, "status": "up"}
)
data = resp.json()

for monitor in data["results"]:
    print(f'{monitor["name"]}: {monitor["status"]}')

print(f'Page {data["page"]} of {data["total_pages"]}')
# Output:
#   Production API — api.example.com: up
#   Checkout Service — checkout.example.com: up
#   CDN Edge — cdn.example.com: up
#   Page 1 of 3

import requests
from datetime import datetime, timezone

MONITOR_ID = "4f2a8c1e-9b3d-47e1-aa5f-0d6c8e21b907"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

resp = requests.get(
    f"https://api.statuspool.io/v1/monitors/{MONITOR_ID}/logs",
    headers=headers,
    params={
        "from": "2025-01-14T00:00:00Z",
        "to": "2025-01-15T00:00:00Z",
        "limit": 20
    }
)
logs = resp.json()["results"]

for entry in logs:
    if entry["status_code"] != 200:
        print(
            f'{entry["timestamp"]} | {entry["region"]}'
            f' | {entry["status_code"]} | {entry["response_time_ms"]}ms'
        )
# Output:
#   2025-01-14T18:31:00Z | ap-northeast-1 | 502 | 8412ms
#   2025-01-14T18:32:00Z | ap-northeast-1 | 502 | 7991ms
#   2025-01-14T18:33:00Z | ap-northeast-1 | 200 | 2103ms

import requests
import hmac
import hashlib
import json

headers = {"Authorization": "Bearer YOUR_API_KEY"}

resp = requests.post(
    "https://api.statuspool.io/v1/webhooks",
    headers=headers,
    json={
        "url": "https://hooks.myapp.io/statuspool",
        "events": ["status_change", "incident_created"],
        "secret": "whsec_a8f3k29d0s1lfj4m7xqwz"
    }
)
webhook = resp.json()
print(f'Webhook ID: {webhook["id"]}')
print(f'Active: {webhook["active"]}')

# Verify incoming webhook signature:
def verify_payload(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
# Usage: verify_payload(body, req.headers["X-Statuspool-Signature"], secret)

curl -X PUT https://api.statuspool.io/v1/monitors/4f2a8c1e-9b3d-47e1-aa5f-0d6c8e21b907 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "interval_seconds": 30,
    "tags": ["production", "api-gateway", "critical"]
  }'

# Response:
# {
#   "id": "4f2a8c1e-9b3d-47e1-aa5f-0d6c8e21b907",
#   "name": "Production API — api.example.com",
#   "interval_seconds": 30,
#   "tags": ["production", "api-gateway", "critical"],
#   "updated_at": "2025-01-15T10:05:33Z"
# }

Code: INVALID_REQUEST

The request body is malformed, missing required fields, or contains invalid values. The details array lists each field-level validation error.

{
  "error": "INVALID_REQUEST",
  "message": "Validation failed",
  "details": [
    {
      "field": "url",
      "message": "Must be a valid HTTP or HTTPS URL"
    },
    {
      "field": "interval_seconds",
      "message": "Must be one of: 30, 60, 120, 300"
    }
  ]
}

Code: UNAUTHORIZED

Missing, expired, or invalid API key. Check that the Authorization: Bearer <token> header is present and the key has not been revoked in the dashboard.

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or expired API key"
}

Code: FORBIDDEN

The authenticated key does not have permission to access the requested resource. This occurs when a read-only key attempts a POST/PUT/DELETE operation, or when accessing a monitor owned by another team.

{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this resource"
}

Code: NOT_FOUND

The requested resource (monitor, webhook, or incident) does not exist or has been deleted. Verify the UUID and ensure the resource belongs to your team.

{
  "error": "NOT_FOUND",
  "message": "Monitor 4f2a8c1e-9b3d-47e1-aa5f-0d6c8e21b907 not found"
}

Code: RATE_LIMITED

Rate limit exceeded (120 requests/minute). The response includes Retry-After header in seconds. Implement exponential backoff in your client.

{
  "error": "RATE_LIMITED",
  "message": "Too many requests. Try again in 12 seconds.",
  "retry_after": 12
}

Code: INTERNAL_ERROR

An unexpected server-side error occurred. Include the request_id from the response header when contacting support at api-support@statuspool.io.

{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Reference: req_8x2k9m4p"
}