API reference

What is the base URL and how do I authenticate?

Every endpoint lives under https://pagelantern.com/api. Authenticate with a bearer token — either an API key (see the API keys guide) or a session token. Requests without one get 401.

All request and response bodies are JSON. Send Content-Type: application/json on anything with a body. Timestamps are ISO 8601 in UTC.

curl -sS https://pagelantern.com/api/monitors \
  -H "Authorization: Bearer $PAGELANTERN_API_KEY" \
  -H "Content-Type: application/json"

What are the core monitor endpoints?

Monitors are the central resource. A monitor carries its target, its type, its schedule and its assertion configuration; creating one starts checking it on the next scheduling pass.

GET    /api/monitors                        list monitors in the workspace
POST   /api/monitors                        create a monitor
GET    /api/monitors/{id}                   read one monitor
PUT    /api/monitors/{id}                   replace a monitor
DELETE /api/monitors/{id}                   delete a monitor
POST   /api/monitors/{id}/run               run a check now, out of band
GET    /api/monitors/{id}/results           recent check results
GET    /api/monitors/{id}/results/{rid}/har HAR capture for one result
POST   /api/monitors/tags                   bulk add or replace tags

How do I create a monitor?

POST a monitor body. Only name, url, intervalSeconds, timeoutMs and enabled are required for an HTTP check; everything else has a default. intervalSeconds must be at least your plan minimum (300s on Free, 60s on Starter, 30s on Team): a request below it is rejected with 402 Payment Required, not silently floored. The web app clamps the field to the plan minimum for you before it submits, so the 402 is something only a direct API caller sees.

curl -sS -X POST https://pagelantern.com/api/monitors \
  -H "Authorization: Bearer $PAGELANTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing site",
    "url": "https://example.com",
    "monitorType": "HTTP",
    "intervalSeconds": 300,
    "timeoutMs": 10000,
    "expectedStatus": 200,
    "bodyContains": "Sign in",
    "availabilityFailureThreshold": 2,
    "availabilityRecoveryThreshold": 2,
    "enabled": true
  }'

What are the incident, status-page and reporting endpoints?

Incidents follow the lifecycle described in the incidents guide. Status-page and analytics endpoints are read-mostly and org-scoped like everything else.

GET    /api/incidents                   list incidents
GET    /api/incidents/{id}              read one incident with its timeline
POST   /api/incidents/{id}/acknowledge  acknowledge
POST   /api/incidents/{id}/resolve      resolve
POST   /api/incidents/{id}/updates      append a timeline update

GET    /api/analytics                    uptime and latency rollups (?range,since,until)
GET    /api/audit                       audit events (Team plan)
GET    /api/billing/usage                plan limits and current usage

How do heartbeats work over the API?

A heartbeat is the one endpoint that does not take a bearer token — the ping URL itself is the credential. Call it from the end of your job, on success only.

#!/bin/sh
set -e

/usr/local/bin/nightly-backup.sh

# Only reached when the backup exits 0 — that is the whole point of a
# dead-man’s switch. Never ping unconditionally or in a trap.
curl -fsS -m 10 --retry 3 "$PAGELANTERN_HEARTBEAT_URL" > /dev/null

What are the rate limits and error conventions?

Authentication-sensitive endpoints are throttled per IP and per account. Ordinary read and write endpoints are not published with a fixed quota; poll no faster than your check interval, because polling faster cannot show you anything newer.

Errors return a JSON body with a message field. 400 means the request was malformed, 401 means the token was missing or rejected, 402 Payment Required means the request exceeded a plan limit (for example a check interval below your plan minimum, or one notification channel too many), 403 means the token was valid but the role is insufficient, 404 means the resource does not exist in your workspace, and 409 means a conflicting concurrent change — re-read and retry.

Every resource is scoped to the workspace the token belongs to. A monitor id from another workspace returns 404, not 403: we do not confirm the existence of resources you cannot see.