Skip to main content
CaptainDNS
✦NEW·Status pages, tied to your monitors. White-label, custom domain, RSS, subscribers.See live demo

Public API changelog

This page lists the major changes to the CaptainDNS public API. Non-breaking additions (new endpoints, new optional fields) are documented here without formal notice. Breaking changes are announced at least 30 days before deployment, on this very page and by email to active key holders.

Versioning policy

  • Backward compatibility: adding optional fields and new endpoints does not break existing clients.
  • Deprecations: a deprecated field or endpoint stays functional for at least 6 months after the announcement.
  • Breaks: breaking changes are announced 30 days ahead and deployed under a new versioned URL (for example /public/v2/*). The V1 URL stays up during the migration window.
  • Version identifier: the OpenAPI spec carries its own version (info.version). The major number follows the versioned URL, the minor number follows backward-compatible additions.

Version 0.3.1 - 2026-05-19

Added

  • POST /public/v1/dmarc/validate: response now includes scoring and recommendations. New additive optional fields: state, score, score_band, verdict_headline, verdict_sub, score_factors, score_breakdown, recommendations, passed_checks, parsed_tags. The existing contract (DMARCAnalysis at root) is strictly preserved. Cost unchanged (1 credit), scope unchanged (mail:read).

Version 0.3.0 - 2026-04-14

Changed

  • Webhook payload: now ships with schema_version: "2". New fields event_id, delivery_id, attempt. User-Agent is now CaptainDNS-Webhook/2.0.
  • New headers on every POST: X-CaptainDNS-Event-ID, X-CaptainDNS-Delivery-ID, X-CaptainDNS-Attempt (format n/6), X-CaptainDNS-Event-Type. Existing headers X-CaptainDNS-Signature and X-CaptainDNS-Timestamp are unchanged.
  • Retry policy: if your endpoint returns 5xx, 408, 429, or a timeout/network error, 6 attempts are made with backoff 10s, 1min, 10min, 1h, 6h, 24h. Other 4xx responses go straight to failed_permanent with no retry.
  • Stable event_id across retries and manual replays: recommended deduplication key on the receiver side.

Version 0.2.0 - 2026-04-09

Added

  • 51 public endpoints under /public/v1/* covering DNS, mail, web and text:
    • DNS: resolve, resolve/propagation, dnssec/check, ip/whois, ip/nslookup, ip/netmask, rdap/lookup, domain/dns-check.
    • Mail: spf/lookup, spf/validate, dkim/lookup, dkim/validate, dmarc/lookup, dmarc/validate, dmarc/generate, dmarcbis/check, dmarcbis/migrate, dmarc/report/analyze, bimi/lookup, bimi/validate, bimi/logo/lookup, mta-sts/lookup, tls-rpt/lookup, dane/lookup, blacklist/ip, smtp/check, mail/header-audit, mail/header-analyze, mail/domain-check, deliverability/score, certificates/csr/parse, certificats/bimi/parse, certificats/bimi/lookup.
    • Web: url/check, page/crawl-check, phishing/check.
    • Text: text/lower, text/upper, text/stats, text/slug, text/base64/encode, text/base64/decode, text/password/generate, text/urlencode, text/urldecode, text/json/format, text/json/to-yaml, text/yaml/format, text/yaml/to-json, text/hash, text/regex/test.
  • API key management from the CaptainDNS dashboard: list, create, revoke, rotate and consult usage.
  • OpenAPI schema PublicAPIError with 10 canonical codes for all public API errors.
  • Stripe-style Idempotency-Key header, 24-hour replay, 409 IDEMPOTENCY_CONFLICT on divergent body.
  • Headers X-Credits-Limit/Remaining/Consumed returned on every successful response.
  • Headers RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining (the latter is written only when a 429 is returned).
  • Header X-Request-Id returned on every response to ease support.
  • 5 billing plans: Free, Starter, Pro, Business, Enterprise, with per-tier quotas and overage billing.
  • Opt-in overage billing with configurable monthly budget cap from the dashboard.
  • Notification channels (webhooks, Slack) on the profile dashboard, with optional HMAC-SHA256 signature and 22 event types. See the dedicated page.

Not shipped in V1

  • Public API webhooks signed by key (webhook_endpoints table) to push account events to your systems.

Stay up to date

  • CaptainDNS blog: major releases are relayed in dedicated posts on captaindns.com/en/blog.
  • Email: active key holders receive an automatic notification for any breaking change.
  • This page: any addition or fix is recorded here, latest first.
  • OpenAPI specification: the info.version field is bumped on each release. Watching its value lets you trigger SDK regenerations.

Next step: go back to the quickstart to start integrating, or explore the OpenAPI reference to see all schemas in detail.