CaptainDNS Public API-Dokumentation

Du willst CaptainDNS-Diagnosen für DNS, Mail und Web aus deinem eigenen Tooling abrufen? Die Public API stellt 51 fokussierte Endpunkte bereit, geschützt durch API-Schlüssel und in Credits abgerechnet. Diese Anleitung führt dich vom ersten curl bis zur produktionsreifen Integration.

Was du bekommst

51 Endpunkte für DNS, Mail und Web: DNS-Auflösung, Propagation, DNSSEC, WHOIS, SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT/DANE, Blacklist, SMTP, Deliverability, Header-Analyse, URL-Checks, Page-Crawl, Phishing, Text-Tools und mehr.
API-Schlüssel im Format cdns_live_... und cdns_test_..., jeweils mit Scopes und rotierbar ohne Ausfallzeit.
Token Bucket pro Schlüssel und Limiter pro IP, um Lastspitzen abzufedern.
Idempotenz im Stripe-Stil, 24-Stunden-Fenster, Wiedergabe gespeicherter Antworten.
Credit-basierte Abrechnung: ein einfacher Lookup kostet 1 Credit, ein Deliverability-Score 30.
Overage-Abrechnung jeden Monatsanfang für bezahlte Pläne, die ihr Kontingent überschreiten.

Basis-URL

https://api.captaindns.com/public/v1

Alle Routen laufen über HTTPS. Die Website www.captaindns.com beherbergt das Dashboard und das Dokumentationsportal, api.captaindns.com beherbergt die API selbst.

Schnellstart in fünf Minuten

1. Einen API-Schlüssel erstellen

Melde dich im CaptainDNS-Dashboard an, öffne Account > API keys, klicke auf Neuer Schlüssel. Wähle einen Namen, eine Umgebung (live oder test), die benötigten Scopes und optional ein Ablaufdatum. Das Klartext-Geheimnis wird nur einmal angezeigt: kopiere es in deinen Secrets-Manager, bevor du den Dialog schließt.

2. Die erste Anfrage senden

curl -X POST https://api.captaindns.com/public/v1/resolve \
  -H "Authorization: Bearer cdns_live_a3f2XK7mN9QrVtZ4yP1sH6eL8cF2dB5aR3gW7kJxM" \
  -H "Content-Type: application/json" \
  -d '{"qname":"captaindns.com","qtype":"A"}'

Die Antwort enthält die angeforderten Datensätze und drei Header-Gruppen zur Steuerung deines Clients:

RateLimit-Policy: "default";q=60;w=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-Credits-Limit: 50000
X-Credits-Remaining: 49998
X-Credits-Consumed: 1
X-Request-Id: req_a1b2c3d4

3. Fehler sauber behandeln

Jede Fehlerantwort folgt derselben JSON-Hülle:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly credits quota reached for the current plan",
  "details": {
    "tier": "starter",
    "limit": 50000,
    "current": 50000
  },
  "request_id": "req_a1b2c3d4"
}

Die häufigsten Codes sind im Fehlerhandbuch beschrieben. Achte besonders auf RATE_LIMITED (429) und QUOTA_EXCEEDED (403): Ersteres wird durch Backoff gelöst, Letzteres erfordert ein Plan-Upgrade oder das Warten auf die nächste Periode.

4. Mit Idempotenz automatisieren

POST-Anfragen akzeptieren einen Idempotency-Key-Header. Jede identische Wiederholung innerhalb von 24 Stunden gibt die ursprüngliche Antwort zurück, mit X-Idempotent-Replay: true. Ideal für clientseitige Netzwerk-Retries. Siehe das Idempotenzhandbuch.

Dokumentationsübersicht

Authentifizierung: Schlüsselformat, IP-Allowlist, Rotation, Widerruf.
Scopes: Aufschlüsselung von dns:read, mail:read, mail:write, web:read.
Credits: Kosten pro Endpunkt, Kontingente pro Plan, Overage-Abrechnung.
Rate Limiting: Token Bucket pro Schlüssel, empfohlener Backoff.
Idempotenz: POST-Wiederholungen, 24 h TTL, Body-Hashing.
Fehler: vollständige Tabelle der Codes und Korrekturmaßnahmen.
OpenAPI-Referenz: interaktive Spezifikation jedes Endpunkts.
Webhooks: kommen in V2.
Changelog: Versionshistorie und Breaking Changes.

Arbeitsprinzipien

Niemals aus dem Browser aufrufen: dein Endnutzer-Frontend ruft dein eigenes Backend auf, das wiederum die CaptainDNS Public API aufruft. Das ist eine Sicherheitsregel: das Geheimnis darf deinen Server nie verlassen.

Observability zuerst: der X-Request-Id-Header wird bei jeder Antwort zurückgegeben. Er wird serverseitig bei CaptainDNS protokolliert und kann zur Öffnung eines Support-Tickets verwendet werden.