CaptainDNS public API documentation

Need to pull CaptainDNS DNS, mail and web diagnostics from your own tooling? The public API exposes 18 focused endpoints, protected by API keys, metered in credits. This guide walks you from the first curl to a production-ready integration.

What you get

40+ endpoints covering DNS, mail, web and text: DNS resolution, propagation, DNSSEC, WHOIS, SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT/DANE checks, blacklist, SMTP, deliverability scoring, URL checks, page crawl, phishing detection, text tools, and more.
API keys in cdns_live_... and cdns_test_... formats, each scoped and rotatable with zero downtime.
Per-key token bucket and per-IP limiter to smooth out bursts.
Stripe-style idempotency, 24 hour window, replays stored responses.
Credit-based metering: a simple lookup costs 1 credit, a deliverability score costs 30.
Overage billing at the start of each month for paid plans that exceed their allowance.

Base URL

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

All routes are HTTPS. The site www.captaindns.com hosts the dashboard and documentation portal, api.captaindns.com hosts the API itself.

Five minute quickstart

Create an API key

Sign in to your CaptainDNS dashboard, open Account > API keys, click the new key button. Pick a name, an environment (live or test), the scopes you need and an optional expiration. The plaintext secret is shown only once: copy it to your secrets manager before closing the dialog.

Fire the first request

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

The response contains the requested records and three families of headers that drive your client behavior:

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

Handle the errors gracefully

Every error shares the same JSON envelope:

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

The most common codes are described in the error guide. Watch out especially for RATE_LIMITED (429) and QUOTA_EXCEEDED (403): the former is solved with backoff, the latter requires a plan upgrade or waiting until the next period.

Automate with idempotency

All POST requests accept an Idempotency-Key header. Any replay within 24 hours returns the original response, with X-Idempotent-Replay: true. Perfect for client-side network retries. See the idempotency guide.

Documentation map

Authentication: key format, IP allowlist, rotation, revocation.
Scopes: breakdown of dns:read, mail:read, mail:write, web:read.
Credits: per-endpoint cost, per-plan quotas, Paddle overage billing.
Rate limiting: per-key token bucket, recommended backoff.
Idempotency: POST replays, 24 h TTL, request body hashing.
Errors: full table of codes and corrective actions.
OpenAPI reference: interactive specification of every endpoint.
Webhooks: shipping in V2.
Changelog: version history and breaking changes.

Operating principles

Never call from the browser: your end-user frontend calls your own backend, which in turn calls the CaptainDNS public API. This is a security rule: the secret must never leave your server.

Observability first: the X-Request-Id header is returned on every response. It is logged server-side at CaptainDNS and can be used to open a support ticket if something breaks.

The same diagnostics are available as web tools, useful for manually checking your integration's output:

DMARC checker to visually compare the detected policy.
SPF checker with lookup count validation.
DNSSEC checker with chain trace from the root.
Blacklist check aggregated over 90+ RBLs.

Ready to code? Read authentication, then move on to rate limiting before your first production deploy.