Monitrxmonitrx-api

API

Everything the dashboard does, over HTTP. Monitors, incidents, status pages, on-call and push are all available, so a deployment can be managed by whatever you already use to manage things.

The address

Every request goes to 

https://monitrx.fyi/api/v1
, or to the address of your own deployment. The dashboard calls the same API, so anything you can do here you can do in a script.

export MONITRX_API="https://monitrx.fyi/api/v1"
export MONITRX_KEY="mxk_..."

Authentication

Send an API key as a bearer token. Keys are created under Settings → API keys and belong to a person, so they carry that person's access.

curl -H "Authorization: Bearer $MONITRX_KEY" \
  "https://monitrx.fyi/api/v1/orgs/acme/monitors"

A key can be read-only, which lets it list monitors and incidents, or read-write, which can also create and change them. The read-only one is the right choice for a script that only reports.

Organisations

Every resource belongs to an organisation, named by its slug. The slug is in the address bar of the dashboard, and the list is here too.

GET/orgsThe organisations you belong to.
GET/orgs/{slug}/monitorsEvery monitor, with its current state.
POST/orgs/{slug}/monitorsCreate a monitor.
GET/orgs/{slug}/monitors/{id}One monitor.
PATCH/orgs/{slug}/monitors/{id}Change a monitor.
DELETE/orgs/{slug}/monitors/{id}Remove a monitor and its history.
GET/orgs/{slug}/monitors/{id}/resultsRecent checks and uptime for a window.
GET/orgs/{slug}/monitors/{id}/seriesThe bucketed history behind the charts.
GET/orgs/{slug}/monitors/seriesThe history for every monitor, in one call.
GET/orgs/{slug}/summaryCounts for the dashboard header.

Incidents

GET/orgs/{slug}/incidentsIncidents, newest first.
GET/orgs/{slug}/monitors/{id}/incidentsOne monitor's incident history.
POST/orgs/{slug}/incidents/{id}/acknowledgeStop the on-call being paged for it.
DELETE/orgs/{slug}/incidents/{id}Remove a resolved incident.

Importing

Monitors can be brought in from another monitoring system, and their history with them.

POST/orgs/{slug}/monitors/import/previewRead a source and list what it contains. Creates nothing.
POST/orgs/{slug}/monitors/importCreate the chosen monitors, and optionally their history.

The source is either an Uptime Kuma instance, read through its own API with a token, or a JSON document pasted in. The document is forgiving about spelling: a name under 

name
or 
label
, an address under 
url
, 
target
, 
address
, 
hostname
or 
host
, and a type as a name or a number.

curl -X POST "$MONITRX_API/orgs/acme/monitors/import" \
  -H "Authorization: Bearer $MONITRX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "json",
    "region": "eu-west",
    "names": ["API", "Website"],
    "payload": [
      {"name": "API", "url": "https://api.example.com", "type": "http", "interval": 60}
    ]
  }'

Status pages

A status page is public, so its read endpoint needs no key. It is also the one that is cached, because strangers read it.

GET/status/{slug}A public status page. No key needed.
GET/status/{slug}/incidentsA page's incident history.
GET/status/{slug}/maintenancesA page's maintenance history.
GET/orgs/{slug}/status-pagesYour status pages.
POST/orgs/{slug}/status-pagesCreate a status page.

On-call and escalation

GET/orgs/{slug}/on-call/schedulesThe rotas.
GET/orgs/{slug}/on-call/schedules/{id}/membersWho is on a rota.
GET/orgs/{slug}/escalation/policiesThe escalation ladders.
GET/orgs/{slug}/push/subscriptionsDevices registered for push.

Errors

Errors come back as JSON with an 

error
and a 
code
that says which kind of thing went wrong, so a script can tell a missing monitor from a bad key without matching on the message.

{
  "error": "monitor not found",
  "code": "not_found"
}