Documentation de l'API publique CaptainDNS

Vous voulez interroger les diagnostics DNS, mail et web de CaptainDNS depuis votre propre outillage ? L'API publique expose plus de 40 endpoints ciblés, protégée par clé, et mesurée en crédits. Ce guide vous emmène du premier curl jusqu'à l'intégration prête pour la production.

Ce que vous obtenez

• Plus de 40 endpoints couvrant DNS, mail et web : résolution DNS, propagation, DNSSEC, WHOIS, SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT/DANE, blacklist, SMTP, délivrabilité, analyse de headers, vérification d'URL, crawl de page, phishing, outils texte, et plus.
• Clés API format cdns_live_... et cdns_test_..., chacune scopée et rotable sans interruption.
• Token bucket par clé et limite par IP pour lisser les pics.
• Idempotence style Stripe, fenêtre de 24 heures, rejoue la réponse stockée.
• Comptabilisation en crédits : un simple lookup coûte 1 crédit, un score de délivrabilité en coûte 30.
• Facturation de l'overage chaque début de mois pour les plans payants qui dépassent leur enveloppe.

Base URL

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

Toutes les routes sont en HTTPS. Le site www.captaindns.com héberge le dashboard et le portail de documentation, api.captaindns.com héberge l'API elle-même.

Démarrage rapide en cinq minutes

1. Créer une clé API

Connectez-vous au dashboard CaptainDNS, ouvrez Account > API keys, cliquez sur Nouvelle clé. Choisissez un nom, un environnement (live ou test), les scopes nécessaires et une date d'expiration facultative. Le secret complet apparaît une seule fois : copiez-le dans votre gestionnaire de secrets avant de fermer la boîte de dialogue.

2. Lancer la première requête

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"}'

La réponse contient les enregistrements demandés et trois familles de headers qui vous servent à piloter le client :

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. Gérer les erreurs

Toutes les erreurs partagent la même enveloppe JSON :

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

Les codes les plus courants sont décrits dans le guide des erreurs. Repérez surtout RATE_LIMITED (429) et QUOTA_EXCEEDED (403) : le premier se règle avec un backoff, le second impose de changer de plan ou d'attendre la fin du mois.

4. Automatiser avec l'idempotence

Les requêtes POST acceptent un header Idempotency-Key. Toute relance identique dans les 24 heures renvoie la réponse d'origine, avec X-Idempotent-Replay: true. Parfait pour les retries réseau côté client. Voir le guide idempotence.

Carte de la documentation

• Authentification : formats de clé, IP allowlist, rotation, révocation.
• Scopes : découpage dns:read, mail:read, mail:write, web:read.
• Credits : coût par endpoint, quotas par plan, overage Paddle.
• Rate limiting : token bucket per-clé, backoff recommandé.
• Idempotence : replay POST, TTL 24 h, hash du body.
• Erreurs : table complète des codes et actions correctives.
• Référence OpenAPI : spécification interactive de tous les endpoints.
• Webhooks : disponibilité prévue en V2.
• Changelog : historique des versions et ruptures.

Principes d'usage

Jamais d'appel navigateur direct : votre frontend utilisateur appelle votre propre backend, qui lui appelle l'API publique CaptainDNS. C'est une règle de sécurité : le secret ne quitte pas votre serveur.

Observabilité en première ligne : le header X-Request-Id est retourné sur chaque réponse. Il est journalisé côté CaptainDNS et réutilisable pour ouvrir un ticket support si quelque chose casse.

Outils CaptainDNS liés

Les mêmes diagnostics sont disponibles en version web, utiles pour vérifier à la main les résultats de votre intégration :

• Vérification DMARC pour comparer visuellement la politique détectée.
• Contrôle SPF avec validation du nombre de lookups.
• Vérification DNSSEC avec trace de chaîne depuis la racine.
• Blacklist check agrégé sur 90+ RBL.

Prêt à coder ? Lisez l'authentification puis passez au rate limiting avant votre première mise en production.