Authentication

All requests are authenticated with a bearer token tied to your workspace. Generate a key from the dashboard under Settings → API Keys.

curl https://api.pulsewatch.io/v1/checks \
  -H "Authorization: Bearer pw_live_xxxxxxxxxxxxxxxx"

Keys are scoped to a workspace and inherit the permissions of the member who created them. Service-level keys for CI pipelines can be created separately under Settings → Service Accounts.

Quickstart

Creating a check takes one request. Pulsewatch starts probing within a few seconds of creation, from the regions you specify.

curl -X POST https://api.pulsewatch.io/v1/checks \
  -H "Authorization: Bearer pw_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-gateway",
    "url": "https://api.example.com/healthz",
    "interval_seconds": 15,
    "regions": ["fra1", "ams3", "lhr1"]
  }'

The response includes a check_id you'll use to fetch results, update the configuration, or attach an alert policy.

Check regions

Checks run from twelve regions across three continents. You can restrict a check to a subset of regions, or let Pulsewatch pick the three closest to your endpoint automatically.

• fra1 — Frankfurt, DE
• ams3 — Amsterdam, NL
• lhr1 — London, UK
• par2 — Paris, FR
• sto1 — Stockholm, SE
• + 7 additional regions, listed in the dashboard

Checks

A check represents one monitored endpoint. Supported check types: http, tcp, grpc_health, and icmp. Each check type accepts its own configuration block — see the full schema in the API reference.

Alert policies

Alert policies define who gets paged, in what order, and after how many consecutive failures. Policies attach to one or more checks and support escalation chains with timeouts between steps.

Status pages

Public status pages read directly from check results — there is no separate "update status" action. Incidents are created automatically when a check policy trips, and resolved automatically when it recovers.

Rate limits

The API allows 300 requests per minute per workspace, with a burst allowance of 50. Check creation is additionally capped at 20 per minute to protect probe scheduling.

Webhooks

Webhook payloads are signed with HMAC-SHA256 using a per-endpoint secret, included as the X-Pulsewatch-Signature header. Verify it before processing the payload.

Error codes

Errors follow a consistent shape: {"error": {"code": "...", "message": "..."}}. Common codes include invalid_request, rate_limited, and endpoint_limit_reached.