API-Dokumentation

Diese Seite ist die kurze, menschenlesbare Einführung. Die vollständige, interaktive Referenz mit allen Feldern, Beispiel-Payloads und einem direkt ausprobierbaren „Try it out“ findest du unter /docs.

Basis-URL & Authentifizierung

Alle Endpunkte liegen unter https://n24dns.de/api/v1/ und erwarten/liefern JSON. Zwei Auth-Arten, je nach Endpunkt-Gruppe:

Bearer-Token (Authorization: Bearer <token>) für Zonen, Records, DynDNS-Hosts und Billing. Token erstellst du im Kundenportal unter „API-Tokens“ – Anzahl und Rate-Limit richten sich nach deinem Tarif.
Session-Cookie für /auth/* und /me – diese beiden Gruppen sind bewusst nicht per API-Token nutzbar, sie gehören zum Login-Flow selbst.

Der dyndns2-Update-Endpoint (/nic/update, /update) ist ein Sonderfall: kein JSON, kein Bearer-Token, sondern das dyndns2-Klartextprotokoll mit dem DynDNS-Host-Update-Token als Passwort – siehe Router-Anleitungen für fertige Konfigurationen je Gerät.

Schnellstart

Alle Zonen der Organisation auflisten:

curl https://n24dns.de/api/v1/zones \
  -H "Authorization: Bearer <dein-api-token>"

Einen DNS-Record anlegen:

curl -X POST https://n24dns.de/api/v1/zones/<zone_id>/records \
  -H "Authorization: Bearer <dein-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "www", "type": "A", "content": "203.0.113.10", "ttl": 300}'

Endpunkte im Überblick

Vollständige Parameter, Antwortschemas und Fehlerfälle stehen bei jedem Endpunkt einzeln unter /docs. Hier nur die Übersicht:

Methode	Pfad	Zweck
GET	/nic/update, /update	dyndns2-Update (Basic Auth bzw. Token-Query-Parameter)
POST	/auth/register	Konto registrieren
POST	/auth/login	Anmelden (Session-Cookie)
GET	/me	Eigenes Konto abrufen
GET	/zones	Zonen auflisten
POST	/zones/platform-subdomains	Subdomain anlegen
POST	/zones/custom-domains	Eigene Domain delegieren
DELETE	/zones/{zone_id}	Zone löschen
GET	/zones/{zone_id}/records	Records auflisten
POST	/zones/{zone_id}/records	Record anlegen
PATCH	/zones/{zone_id}/records/{record_id}	Record ändern
DELETE	/zones/{zone_id}/records/{record_id}	Record löschen
GET	/zones/{zone_id}/dyndns-hosts	DynDNS-Hosts auflisten
POST	/zones/{zone_id}/dyndns-hosts	DynDNS-Host anlegen
GET	/billing/plans	Tarife auflisten (kein Login nötig)
GET	/billing/subscription	Aktuelles Abo abrufen
GET	/billing/usage	Nutzung gegen Plan-Limits

dyndns2-Antwortcodes

Der Update-Endpoint antwortet HTTP 200 mit Klartext (oder JSON bei Accept: application/json) – Fehler stehen im Antworttext, nicht im HTTP-Status, wie beim klassischen dyndns2-Protokoll üblich:

Antwort	Bedeutung
good <ip>	Update erfolgreich, IP wurde geändert.
nochg <ip>	IP war bereits aktuell, kein Schreibvorgang nötig.
badauth	Update-Token fehlt oder ist ungültig.
nohost	Zum Token gehört kein bekannter DynDNS-Host.
notfqdn	Angefragter Hostname ist kein gültiger vollständiger Domainname.
abuse	Rate-Limit für diesen Host überschritten.
911	Interner Fehler, später erneut versuchen.

Fehlerformat (JSON-Endpunkte)

Alle Fehler der JSON-API haben dieselbe Form, unabhängig vom HTTP-Status:

{"error": "limit_exceeded", "message": "..."}

HTTP	error	Bedeutung
401	authentication_failed	Token/Login fehlt oder ungültig.
402	limit_exceeded	Tarif-Limit erreicht (z. B. Anzahl Zonen, DynDNS-Hosts, TTL-Minimum).
403	not_authorized	Authentifiziert, aber ohne Rechte für diese Aktion.
404	not_found	Ressource existiert nicht oder gehört einer anderen Organisation.
409	conflict	Kollision mit bestehenden Daten (z. B. CNAME-Konflikt, Label bereits vergeben).
422	validation_failed	Eingabe ungültig.
429	rate_limited	Rate-Limit überschritten, `Retry-After`-Header beachten.
502	upstream_service_error	Ein externer Dienst (z. B. PowerDNS) war nicht erreichbar.

API-Tokens & Rate-Limits je Tarif

Der kostenlose Free-Tarif hat keinen API-Zugriff (0 Tokens) – ab Home ist die API nutzbar, Details und weitere Limits auf der Preisübersicht:

Tarif	API-Tokens	Rate-Limit
Free	0	kein API-Zugriff
Home	2	60 Requests/Minute
Business	10	300 Requests/Minute
Company	50	1200 Requests/Minute

Vollständige Referenz

Jeder Endpunkt einzeln mit allen Feldern, Beispiel-Payloads und direktem „Try it out“ gegen die echte API:

Zur interaktiven API-Referenz