REST API

Authenticate with an API token and manage monitors, incidents and status pages over HTTP.

Everything in the dashboard is available through a JSON REST API under /api/v1. The OpenAPI specification is the source of truth for every endpoint.

Authentication

API tokens come with Team and Business. An admin or the owner creates one under Settings → API tokens: a name, a scope and, if you like, an expiry. The token — it starts with hmd_ — is shown once, right after it is created; Heimdall stores only a hash of it, so save it in your secret store then. Send it with every request:

curl

curl -s https://heimdall.warewave.tech/api/v1/monitors \
  -H "Authorization: Bearer $HEIMDALL_API_TOKEN"

Scope	What the token can do
`read`	Everything a viewer sees: monitors, results, incidents, status pages, on-call, messages
`write`	What a member may do as well: create and change monitors, snooze and resolve incidents, post status page updates and maintenance

A token belongs to one organisation. For another organisation, create a token there.
Tokens never reach profiles, users, API tokens, billing or organisation settings, whatever their scope.
401 with code invalid_token: the token is unknown, revoked or has expired.
402 with code plan_limit: the organisation’s plan no longer includes the API. The tokens are kept and work again after an upgrade.
403 with code forbidden: the token’s scope does not allow the request, for example a read token on a POST.
429: too many requests with this token; Retry-After says how many seconds to wait.
Revoke a token under Settings → API tokens; it stops working at once.

Common endpoints

Method	Path	Purpose
GET	`/api/v1/monitors`	List monitors
POST	`/api/v1/monitors`	Create a monitor
POST	`/api/v1/monitors/{id}/pause`	Pause a monitor
GET	`/api/v1/incidents`	List incidents
POST	`/api/v1/incidents/{id}/ack`	Acknowledge an incident
POST	`/api/v1/incidents/{id}/snooze`	Pause escalation
GET	`/api/v1/events/stream`	Live events (Server-Sent Events)

Live events

/api/v1/events/stream is a Server-Sent Events stream of monitor state changes and incident updates. It is what the dashboard itself uses.

Event

event: monitor.state
data: {"monitor_id":"mon_01J9Z…","state":"down","regions":{"ist":"failing","stc":"failing","fra":"failing"}}