Setup documentation

Docs

Everything you need to connect a project to Status, expose a working /api/health endpoint, and surface the results on your own site.

Getting started

Five steps from “no endpoint” to a live status page for your project.

Step 1 — Check the requirements

Requirement	Detail
Public HTTPS URL	The health URL must start with https://. Self-signed certs will fail.
Anonymous access	No API keys, sessions, or IP allow-lists on the health endpoint.
Low latency	Must return within 15 seconds. Each poll waits serially per project.
Lowercased statuses	ok, degraded, down (case is normalized anyway).

If you cannot add an endpoint yet: paste the URL of any existing page (e.g. https://your-store.com). The poller will record a single site component that is downwhen the page is unreachable and ok otherwise. Real per-component visibility needs the JSON endpoint.

Step 2 — Expose your health endpoint

Create GET /api/health that returns the full health of your stack as JSON. Each entry is one component (for example site, db, cache, auth, payments).

{
  "status": "ok",
  "results": [
    { "id": "site",  "label": "Website",    "status": "ok",       "latencyMs": 41 },
    { "id": "db",    "label": "Database",   "status": "ok",       "latencyMs": 12 },
    { "id": "cache", "label": "Redis",      "status": "degraded", "latencyMs": 230 }
  ]
}

Grab a ready-made implementation from the code examples. The full field-by-field contract is on the contract page.

Step 3 — Test it locally

Any request tool works. The status app fetches server-side, so CORS is not required for the check itself.

curl -s https://your-store.com/api/health | jq

# Expect an object with "status" and a "results" array.
# A broken/empty body will be surfaced as a "site": down component.

Step 4 — Register the project

Two paths to the same result:

Self-serve (recommended) — open the flagship /admin console, unlock with the admin key, and use New project: fill the display name, a slug you like (lowercase, hyphens), and the health URL.
Assisted — send us the name, the slug you want, and the health URL; we add it for you.

Pro tip: after adding the project, hit Run poll now in the admin console to get the first check instantly instead of waiting for the 5-minute cycle.

Step 5 — Verify and share

Open /p/[slug] — you should see every component with a per-window uptime bar.
Simulate a fault (stop your DB, or return degraded) and run the poll again — the page should reflect it.
Share the page, or surface it on your own site via an embed or the JSON API.

Your project page, inside out

Section	What it shows
Current status	down if any component is down, else degraded if any is degraded, else ok.
Uptime (24h / 7d / 30d)	ok / (ok + degraded + down) over the selected window, to one decimal.
Components	Per-component dot, uptime %, and average latency for the window.
Uptime calendar	One year of per-day rollups. Amber = degraded day, red = day with any downtime. Click a day for the per-component breakdown and incident list.
Incidents	Every day in the last 12 months that had at least one down result.