Reporting API

Drive a status page from an external monitor - open incidents, post updates, and set component statuses with a per-page Status API key.

Reporting API#

Most of Status is built in the dashboard, but you can also drive a page programmatically. Create a Status API key for a page, then have an external monitor or script open incidents, post updates, and set component statuses. Writes go through the same path the dashboard uses, so the public page, subscriber notifications and the 90-day uptime stay consistent.

A key is scoped to a single page: it can only read and write the page it was created for.

Authentication#

Create a key from the page editor in the dashboard. It is shown in full once when you create or rotate it; store it somewhere safe. Send it on every request:

Authorization: Bearer hyd_status_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• A key authorizes only its own page. There is no account-wide Status key.
• Revoke a key by deleting or disabling it in the dashboard; revocation takes effect immediately.

Status values#

Two enums are used throughout. Sending a value outside these sets returns 400.

• Component status: operational, degraded, partial, outage, maintenance.
• Incident state: investigating, identified, in_progress, monitoring, resolved.
• Incident impact: none, minor, major, critical.

Anywhere you set affected components you pass an array of { component, status }, where component is the component's id or its name (case-insensitive). Unknown references are ignored silently, so a rename never breaks a caller.

Read current status#

{
  "ok": true,
  "data": {
    "overall": "operational",
    "components": [
      { "id": "c_api", "name": "API", "status": "operational" }
    ],
    "activeIncidents": [
      { "id": "i_123", "title": "Elevated latency", "state": "monitoring", "impact": "minor", "startedAt": "2026-06-08T18:00:00.000Z" }
    ]
  }
}

Open an incident#

curl -X POST https://api.hep.gg/v1/status-api/incidents \
  -H "Authorization: Bearer hyd_status_xxx" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Elevated API latency",
        "impact": "minor",
        "body": "We are investigating elevated latency.",
        "components": [{ "component": "API", "status": "degraded" }]
      }'

const res = await fetch("https://api.hep.gg/v1/status-api/incidents", {
  method: "POST",
  headers: {
    Authorization: "Bearer hyd_status_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Elevated API latency",
    impact: "minor",
    body: "We are investigating elevated latency.",
    components: [{ component: "API", status: "degraded" }],
  }),
});
const { data } = await res.json();
console.log(data.id); // new incident id

{ "ok": true, "data": { "id": "i_123" } }

Post an update / change state#

Moving an incident to resolved auto-resets every component the incident touched back to operational and closes out its contribution to the uptime history.

{ "ok": true, "data": { "id": "u_456" } }

Set a component status#

curl -X POST https://api.hep.gg/v1/status-api/components/c_api/status \
  -H "Authorization: Bearer hyd_status_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "operational" }'

{ "ok": true }

Behaviour notes#

• Setting a component's status counts toward its 90-day uptime, exactly like a change made in the dashboard. Maintenance never counts as downtime.
• Resolving an incident restores the components it affected to Online, except components that another open incident is still affecting. Pass restore on the resolving update ("all", "none", or a list of component ids) to control this explicitly.
• POST /incidents also accepts optional state, kind (incident or maintenance) and, for maintenance, scheduledFor and scheduledUntil. A maintenance scheduled for later is created as scheduled and its components are applied at the start time.
• Both POST /incidents and POST /incidents/:id/updates accept notify: true to notify the page's subscribers.
• Incidents and updates created through the API are marked with their source in the dashboard history.