Authentifizierung
API-Tokens erzeugen Admins und Owner im Dashboard unter Einstellungen → API. Das Token wird genau einmal im Klartext angezeigt; danach ist nur noch Name, Recht, letzte Nutzung und Ablauf sichtbar. Jeder Aufruf schickt das Token als Bearer-Token und fordert JSON an:
- Ein Token gilt für genau eine Organisation. Aufrufe für eine andere Organisation antworten mit 404, als gäbe es sie nicht.
- Optionales Ablaufdatum von 1 bis 730 Tagen; empfohlen sind 90 Tage mit regelmäßiger Erneuerung. Abgelaufene und widerrufene Tokens antworten mit 401.
- Verlässt der Ersteller die Organisation oder wird die Organisation gelöscht, sind seine Tokens sofort ungültig.
- Höchstens 20 Tokens je Organisation. Jedes Anlegen und Widerrufen steht im Audit-Log.
Authorization: Bearer <Token>
Accept: application/jsonRechte: read und write
Beim Anlegen wählst du zwischen zwei Rechten. Ein Token hat nie mehr Rechte als ein Mitglied, auch wenn ein Owner es erzeugt hat.
- read: wie die Rolle Viewer. Alle GET-Endpunkte; jede schreibende Methode antwortet mit 403.
- write: wie die Rolle Mitglied. Zusätzlich Domains und Kunden anlegen, ändern und löschen, Monitore verwalten, Prüfungen anstoßen und Incidents quittieren.
- Nie per Token, auch nicht mit write: Konto, Passwort, Zwei-Faktor, Passkeys, Mitglieder, Einladungen, Abrechnung, Benachrichtigungskanäle, Audit-Log, Datenexport und die Token-Verwaltung selbst. Diese Routen antworten mit 403.
Basis-Adresse und Sprache
Alle Endpunkte liegen unter https://api.domainwarn.com/api/v1; die Daten einer Organisation unter /orgs/{organization}. Den Slug findest du in der Adresse des Dashboards, unter Einstellungen → API oder über GET /organizations, das mit einem Token genau die eine Organisation liefert.
Befunde (findings) sind übersetzt: mit dem Header Accept-Language: de oder en bestimmst du die Sprache, ohne Header ist sie Englisch. Alle Zeitpunkte sind ISO 8601 in UTC (Endung Z), IDs sind UUIDs.
Limits
- 300 Anfragen je Minute und Token, unabhängig von der Dashboard-Sitzung des Erstellers. Die Header
X-RateLimit-LimitundX-RateLimit-Remainingzeigen den Stand; bei Überschreitung antwortet der Server mit 429 undRetry-Afterin Sekunden. - Jetzt prüfen: 5 Aufrufe je Domain und Stunde, 60 je Organisation und Stunde.
- Sammelimport: 200 Domains je Aufruf, 3 Aufrufe je Stunde und Organisation.
- Das Domainlimit des Tarifs gilt auch für die API. Darüber hinaus angelegte Domains antworten mit 422; Domains über dem Limit eines kleineren Tarifs sind
plan_paused.
Antworten und Fehler
Erfolgreiche Antworten tragen die Nutzdaten unter data; Listen zusätzlich links und meta. Anlegen antwortet mit 201, Löschen mit 204 ohne Inhalt, Prüfungen anstoßen mit 202. Jeder Fehler kommt als application/problem+json (RFC 9457) mit type, title, status und meist detail:
- 401: Token fehlt, ist abgelaufen oder widerrufen.
- 402: Die Organisation ist gesperrt oder hat keinen aktiven Tarif;
planundsuspendedsagen, warum. - 403: Das Token darf das nicht (Lese-Token bei schreibender Methode, gesperrter Bereich).
- 404: Organisation oder Objekt nicht gefunden, auch bei einer fremden Organisation.
- 422: Eingabe ungültig;
errorsenthält die Meldungen je Feld. - 429: Limit überschritten, siehe
Retry-After.
{
"type": "https://domainwarn.com/errors/validation",
"title": "Die Eingabe ist ungültig.",
"status": 422,
"detail": "Der Name muss ausgefüllt sein.",
"errors": { "name": ["Der Name muss ausgefüllt sein."] }
}Paginierung
Domains und Kunden sind seitenweise paginiert: page und per_page als Parameter, meta.current_page, meta.last_page und meta.total in der Antwort. Incidents, Ereignisse und Prüfergebnisse sind nach Zeit sortiert und cursor-paginiert: die Antwort nennt in meta.next_cursor (bei Prüfergebnissen links.next) den Cursor der nächsten Seite, den du als Parameter cursor mitgibst; null heißt Ende.
GET /orgs/meine-agentur/incidents?status=open&per_page=100
GET /orgs/meine-agentur/incidents?status=open&per_page=100&cursor=eyJzdGFydGVkX2F0Ijoi…Beispiel: kritische Domains abfragen
Alle Domains mit kritischem Zustand, sortiert nach Zustand, als Grundlage für ein Ticket-System oder einen Slack-Bot:
curl -H "Authorization: Bearer $DOMAINWARN_TOKEN" -H "Accept: application/json" \
"https://api.domainwarn.com/api/v1/orgs/meine-agentur/domains?status=critical,warning&sort=health_status"Beispiel: Domain aus der CI anlegen und prüfen
Nach dem Go-live einer Kundenseite legt die Pipeline die Domain an und stößt sofort die erste Prüfung an. Die Antwort auf das Anlegen enthält die id für alle weiteren Aufrufe:
curl -X POST -H "Authorization: Bearer $DOMAINWARN_TOKEN" -H "Accept: application/json" \
-H "Content-Type: application/json" -d '{"name":"kunde.de","customer_id":"3f9c1a52-6a2e-4c0e-9d4b-1c9a1a0e5b77"}' \
"https://api.domainwarn.com/api/v1/orgs/meine-agentur/domains"
curl -X POST -H "Authorization: Bearer $DOMAINWARN_TOKEN" -H "Accept: application/json" \
"https://api.domainwarn.com/api/v1/orgs/meine-agentur/domains/<domain-id>/check-now"Code-Beispiele für curl, PHP, Python, JavaScript, Go und PowerShell
Sprache bzw. Werkzeug und Anwendungsfall auswählen; <TOKEN> durch dein Token ersetzen. Anwendungsfälle mit Schreibzugriff sind markiert und brauchen ein Token mit Schreibrecht.
GET /domainsLese-Token genügtcurl "https://api.domainwarn.com/api/v1/orgs/meine-agentur/domains?status=critical,warning&sort=health_status" \
-H "Authorization: Bearer <TOKEN>" \
-H "Accept: application/json"„meine-agentur“ steht für den Slug deiner Organisation; im Dashboard unter Einstellungen → API stehen die Beispiele mit deiner Adresse.
Im Editor fragen (MCP)
DomainWarn ist selbst ein MCP-Server: POST /mcp spricht das Model Context Protocol, und Editoren und Assistenten binden es mit einer Adresse und dem Token ein – nichts zu installieren. Der Assistent beantwortet damit Fragen wie „Welche Kundendomains sind gerade kritisch?“ oder „Prüf kunde.de“ mit deinen echten Daten.
Neun Werkzeuge in drei Stufen: Ohne Token laufen die kostenlosen Prüfungen (check_domain, run_check), mit Token kommen list_domains, get_domain, list_incidents und get_dns_history dazu, und ein Token mit Schreibrecht schaltet add_domain, check_now und acknowledge_incident frei. Mit einem Lese-Token erscheinen die schreibenden Werkzeuge gar nicht erst.
Im Terminal ausführen; mit --scope user steht DomainWarn in allen Projekten bereit.
claude mcp add --transport http domainwarn https://api.domainwarn.com/api/v1/mcp \
--header "Authorization: Bearer <TOKEN>"Monitoring-Systeme anbinden
Prometheus, Grafana Alloy, VictoriaMetrics, Telegraf und Datadog lesen die Kennzahlen aller Domains im Prometheus-Format unter /orgs/{organization}/metrics; Checkmk, Nagios/Icinga, Uptime Kuma und PRTG fragen die JSON-Übersicht /orgs/{organization}/dashboard ab und schlagen an, sobald eine Domain kritisch ist. System auswählen und die fertige Konfiguration übernehmen:
Scrape-Job für die prometheus.yml; danach stehen alle Kennzahlen für Grafana und Alertmanager bereit. (Nutzt die Prometheus-Metriken)
scrape_configs:
- job_name: domainwarn
scheme: https
metrics_path: /api/v1/orgs/meine-agentur/metrics
scrape_interval: 60s
static_configs: [{ targets: ['api.domainwarn.com'] }]
authorization: { credentials: '<TOKEN>' }„meine-agentur“ steht für den Slug deiner Organisation; im Dashboard unter Einstellungen → API stehen die Beispiele mit deiner Adresse.
OpenAPI-Spezifikation
Die vollständige Beschreibung aller Endpunkte, Parameter, Schemata und Fehler gibt es als OpenAPI 3.1 unter /openapi.json in der Sprache dieser Seite. Damit erzeugst du Clients (openapi-generator, orval, Kiota), importierst die API in Postman, Insomnia oder Bruno oder öffnest sie im Swagger Editor. Die Spezifikation wird aus derselben Quelle wie diese Seite gebaut und ändert sich mit jedem Release der API.