Zum Inhalt springen

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

  1. Öffnen Sie Einstellungen → API-Token.
  2. Kopieren Sie das Token und schicken Sie es bei jeder Anfrage im Header Authentication-Token mit:
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.