CaptainDNS Public API-Dokumentation

Möchten Sie CaptainDNS-Diagnosen für DNS, Mail und Web aus Ihrem eigenen Tooling abrufen? Die Public API stellt 18 fokussierte Endpunkte bereit, geschützt durch API-Schlüssel und in Credits abgerechnet. Diese Anleitung führt Sie vom ersten curl bis zur produktionsreifen Integration.

Was Sie erhalten

Über 40 Endpunkte, sorgfältig ausgewählt: DNS-Auflösung, SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT-Prüfungen, Blacklist, SMTP, Deliverability, URL-Checks, Page-Crawl und Phishing-Erkennung.
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 25.
Overage wird monatlich abgerechnet 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

Einen API-Schlüssel erstellen

Melden Sie sich im CaptainDNS-Dashboard an, öffnen Sie Account > API keys, klicken Sie auf den Button für einen neuen Schlüssel. Wählen Sie einen Namen, eine Umgebung (live oder test), die benötigten Scopes und optional ein Ablaufdatum. Das Klartext-Geheimnis wird nur einmal angezeigt: kopieren Sie es in Ihren Secrets-Manager, bevor Sie den Dialog schließen.

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 Ihres 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

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 werden im Fehlerhandbuch beschrieben. Achten Sie 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.

Mit Idempotenz automatisieren

Alle POST-Anfragen akzeptieren einen Idempotency-Key-Header. Jede 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

Gemeinsame Handler mit der internen API: jeder öffentliche Endpunkt verwendet denselben Handler wie sein internes /v1/*-Gegenstück. Jeder Bugfix für das Frontend kommt automatisch den Drittanbieter-Integrationen zugute, ohne Duplikation und ohne stille Drift.

Niemals aus dem Browser aufrufen: Ihr Endnutzer-Frontend ruft Ihr eigenes Backend auf, das wiederum die CaptainDNS Public API aufruft. Das ist eine Sicherheitsregel: das Geheimnis darf Ihren 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.