API documentatie

Beheer je monitors en heartbeats via een eenvoudige REST API. Geen SDK nodig, curl volstaat.

Snel beginnen

De API woont op https://alerted.nl/v1. Alle responses zijn JSON. Tijden zijn Unix timestamps (seconden sinds 1970, UTC). De CSV-export converteert daarnaast naar ISO 8601. Alle endpoints vereisen een API-sleutel, behalve /ping/… heartbeats.

# Eerste site toevoegen
curl -X POST https://alerted.nl/v1/monitors \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://mijnsite.nl","interval":60}'

Demo-mode: tijdens deze prototype-fase bestaat /v1/_demo/* als openbaar, auth-vrij speelterrein. Probeer eerst curl https://alerted.nl/v1/_demo/health om te zien dat het werkt. Zie ook /v1/_demo/monitors (GET + POST, rate-limited 10/min).

Authenticatie

Maak een API-sleutel aan op /instellingen. Stuur de sleutel mee in de Authorization-header met prefix Bearer.

curl -H "Authorization: Bearer ak_live_8f3a2b1c..." \
  https://alerted.nl/v1/monitors

Sleutels beginnend met ak_live_ zijn productie. ak_test_ zijn testsleutels (raken niet je quota en versturen geen alerts).

Rate limits

Tijdens deze prototype-fase zijn auth-endpoints (/v1/monitors etc.) niet rate-limited. Demo-endpoints (/v1/_demo/*) zijn beperkt tot 10 POST's per minuut per IP; bij overschrijding 429. Heartbeat-pings hebben geen limiet.

Site toevoegen

POST /v1/monitors

Voeg een site toe die we in de gaten gaan houden. Retourneert het volledige monitor-object inclusief gegenereerde id.

Veld	Type		Toelichting
url	string	VEREIST	Volledige URL inclusief `https://`.
naam	string		Hoe je 'm in het dashboard ziet (max 120 tekens). Optioneel; het dashboard valt anders terug op de URL.
interval	integer		Seconden tussen checks (`30` tot `86400`). Standaard `300`. UI biedt 30 / 60 / 300.
kanalen	array		Lijst kanaal-id's, max 8. Operationeel: `push`, `mail`. Gepland: `sms`, `signal`, `webhook`, `slack`.

curl -X POST https://alerted.nl/v1/monitors \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mijnsite.nl",
    "naam": "Mijn webshop",
    "interval": 60,
    "kanalen": ["push", "mail"]
  }'

Alle sites ophalen

GET /v1/monitors

Geeft alle sites in je account. Optionele query-parameter status=down filtert op problemen.

curl -H "Authorization: Bearer ak_live_..." \
  https://alerted.nl/v1/monitors

Site-detail

GET /v1/monitors/{id}

Details inclusief huidige status, uptime-percentages en de meest recente storingen.

curl -H "Authorization: Bearer ak_live_..." \
  https://alerted.nl/v1/monitors/abc123

Site verwijderen

DELETE /v1/monitors/{id}

Verwijdert de site en alle bijbehorende historie. Niet ongedaan te maken.

curl -X DELETE \
  -H "Authorization: Bearer ak_live_..." \
  https://alerted.nl/v1/monitors/abc123

Heartbeat aanmaken

POST /v1/heartbeats

Maak een heartbeat aan voor een geplande taak (cron, backup, batch-job). Retourneert een ping-URL die je script aanroept zodra de taak klaar is. Blijft een ping langer dan het interval uit, dan krijg je een seintje.

Veld	Type		Toelichting
naam	string		Hoe je 'm in het dashboard ziet (max 120 tekens).
interval	integer		Verwachte seconden tussen pings. `60` tot `2592000` (1 minuut tot 30 dagen). Standaard `86400` (dagelijks).

curl -X POST https://alerted.nl/v1/heartbeats \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"naam":"Nachtelijke back-up","interval":86400}'

De response bevat een ping_path, bijvoorbeeld /v1/ping/hb_8f3a2b1c. Je cron roept dat pad daarna bij elke geslaagde run aan op https://alerted.nl/v1/ping/hb_8f3a2b1c (zie Ping), en bij een fout POST .../fail (zie Ping als mislukt).

GET /v1/heartbeats

Geeft alle heartbeats in je account, inclusief laatste ping en status.

curl -H "Authorization: Bearer ak_live_..." \
  https://alerted.nl/v1/heartbeats

DELETE /v1/heartbeats/{id}

Verwijdert de heartbeat en de bijbehorende ping-URL. Niet ongedaan te maken.

curl -X DELETE \
  -H "Authorization: Bearer ak_live_..." \
  https://alerted.nl/v1/heartbeats/hb_8f3a2b1c

Heartbeat-ping

GET /v1/ping/{id}

Ping vanuit je cronjob of script om te bevestigen dat een geplande taak is gelukt. Geen authenticatie nodig, de id is zelf de geheime sleutel.

# In je crontab
0 3 * * * /usr/local/bin/backup.sh && \
  curl -s https://alerted.nl/v1/ping/a1b2c3

Als er meer dan het ingestelde interval voorbijgaat zonder ping, sturen we een seintje dat de taak te laat is.

Heartbeat als mislukt

POST /v1/ping/{id}/fail

Meld actief dat een taak is mislukt, zonder te wachten op een timeout. Optioneel een korte boodschap in de body.

curl -X POST https://alerted.nl/v1/ping/a1b2c3/fail \
  -d "Database-dump faalde, exit-code 2"

Recente storingen

GET /v1/incidents

Alle storingen, nieuwste eerst. Filter met since=2026-05-01 of monitor_id=abc123.

curl -H "Authorization: Bearer ak_live_..." \
  "https://alerted.nl/v1/incidents?since=2026-05-01"

Status-badge

GET /v1/_demo/badge/{id}.svg

Embeddable SVG-badge in shields.io-stijl, geen auth nodig. Cache-Control: max-age=60.

Status-mapping: up → groen "online", warn → amber "traag", down → rood "offline", paused → grijs "gepauzeerd".

<!-- Embed in je footer of README -->
<img src="https://alerted.nl/v1/_demo/badge/mon_klant.svg" alt="status">

In Markdown:

![status](https://alerted.nl/v1/_demo/badge/mon_klant.svg)