API
REST-API zur Zertifikatsüberwachung: Domains anlegen, löschen und neu prüfen, Health-Scores und Verlauf abrufen. Token-Authentifizierung, JSON, ab Starter.
Mit der REST-API automatisieren Sie, was Sie sonst im Browser erledigen: Domains anlegen und
entfernen, Prüfungen anstoßen und Health-Scores abrufen. Sie steht in Starter und Pro unter
/api/v1/... zur Verfügung. Anfragen und Antworten sind durchgehend JSON.
Token abrufen
- Öffnen Sie Einstellungen → API-Token.
- Kopieren Sie das Token und schicken Sie es bei jeder Anfrage im Header
Authentication-Tokenmit:
curl https://certwatchr.com/api/v1/domains \
-H 'Authentication-Token: <IHR-TOKEN>'
Behandeln Sie das Token wie ein Passwort: Wer es kennt, kann Ihre Domains anlegen, löschen und einsehen. Ist es in einem geteilten Log, einer CI-Ausgabe oder auf einem Screenshot gelandet, sollten Sie es erneuern.
Token erneuern auf derselben Seite erzeugt ein neues Token und macht das alte sofort ungültig. Passen Sie Ihre Skripte daher gleich danach an. Ihre Sitzung in der Weboberfläche bleibt davon unberührt – und umgekehrt ändert eine Passwortänderung nichts am Token.
Domains
GET /api/v1/domains # Domains auflisten
POST /api/v1/domains # Domain anlegen
DELETE /api/v1/domains/<id> # Domain entfernen
POST /api/v1/domains/<id>/check # Zertifikat sofort prüfen
Domain anlegen
curl -X POST https://certwatchr.com/api/v1/domains \
-H 'Authentication-Token: <IHR-TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"hostname":"example.com","port":443,"alert_at_days":30,"tags":["prod","web"]}'
| Feld | Pflicht | Hinweise |
|---|---|---|
hostname |
ja | Wird automatisch kleingeschrieben und um Leerzeichen bereinigt. Höchstens 255 Zeichen. |
port |
nein | 1–65535, Standard 443. |
label |
nein | Höchstens 128 Zeichen. |
alert_at_days |
nein | 1–365, Standard 30. |
tags |
nein | Als Liste (["prod","web"]) oder kommagetrennt als String ("prod,web"). Gespeichert wird genauso wie über das Formular. |
Ist dieselbe Kombination aus Hostname und Port schon angelegt, antwortet die API mit 409 Conflict und lässt die bestehende Domain unverändert. Ein Skript können Sie also bedenkenlos mehrfach laufen lassen. Das Domain-Limit Ihres Tarifs gilt genauso wie im Browser.
Domain-Objekte
Jede Domain wird in diesem Format zurückgegeben:
{
"id": 42,
"hostname": "example.com",
"port": 443,
"label": "Hauptseite",
"tags": ["prod", "web"],
"alert_at_days": 30,
"status": "ok",
"days_remaining": 67,
"cert_expiry": "2026-11-28T09:14:00",
"cert_issuer": "Let's Encrypt",
"cert_subject": "example.com",
"last_checked_at": "2026-09-22T06:00:12",
"alerts_snoozed_until": null
}
status ist einer der Werte untested, ok, warning, critical oder error.
POST .../check antwortet mit 202 {"queued": true}; das Ergebnis steht wenige Sekunden später
an der Domain.
Health-Score
GET /api/v1/domains/<id>/health # aktueller Score, Aufschlüsselung, Vorschläge
POST /api/v1/domains/<id>/health/check # Health-Prüfung sofort starten
GET /api/v1/domains/<id>/health/history?limit=90 # Verlauf, älteste Prüfung zuerst
GET /health liefert das gespeicherte Ergebnis, ohne neu zu prüfen:
{
"health_score": 90,
"breakdown": {
"chain_trusted": 20,
"hostname_match": 15,
"not_yet_valid": 5,
"expiry_proximity": 20,
"revocation": 10,
"chain_complete": 0,
"tls_version": 10,
"weak_algorithms": 10
},
"certificate": {
"subject": "example.com",
"issuer": "Let's Encrypt",
"days_remaining": 67
},
"errors": ["Incomplete chain: server did not send its intermediate certificate"],
"suggestions": [
{
"category": "chain_complete",
"points": 10,
"severity": "critical",
"title": "Send the intermediate certificates too",
"why": "..."
}
],
"last_health_checked_at": "2026-09-22T06:30:00"
}
Kategorien und Punktzahlen entsprechen denen auf der Seite Health-Score.
suggestions enthält dieselben Verbesserungsvorschläge wie die Seite der Domain, das Dringendste
zuerst.
history liefert pro vergangener Prüfung einen Eintrag mit health_score, breakdown,
tls_version, signature_algorithm, errors und checked_at. limit ist standardmäßig 90,
höchstens 365.
Fehler
Jeder Fehler kommt als JSON mit passendem HTTP-Status zurück – auch wenn die Authentifizierung scheitert. Eine HTML-Seite oder eine Weiterleitung zur Anmeldung bekommen Sie nie:
{"error": "Conflict", "message": "example.com:443 is already being monitored."}
| Status | Bedeutung |
|---|---|
400 |
Der Body ist kein gültiges JSON, oder ein Feld ist ungültig. Welches, steht in der Meldung. |
401 |
Authentication-Token fehlt oder ist ungültig. |
403 |
Ihr Tarif umfasst diesen Endpunkt nicht, die Domain gehört nicht zu Ihrem Konto, oder Ihr Domain-Limit ist erreicht. |
404 |
Domain nicht gefunden. |
409 |
Hostname und Port werden in Ihrem Konto bereits überwacht. |
5xx-Antworten können Sie nach kurzer Wartezeit einfach wiederholen. Bei 4xx-Antworten bringt
eine Wiederholung nichts – hier muss die Anfrage selbst angepasst werden.