Documentação da API pública CaptainDNS

Quer consultar os diagnósticos DNS, email é web do CaptainDNS a partir do seu proprio tooling? A API pública expoe 40+ endpoints selecionados, protegidos por chave é medidos em créditos. Este guia leva você do primeiro curl a uma integração pronta para produção.

O que você obtem

• 40+ endpoints cuidadosamente selecionados: resolução DNS, verificação SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT, blacklist, SMTP, deliverability, URL check, page crawl é detecção de phishing.
• Chaves API nos formatos cdns_live_... é cdns_test_..., cada uma com escopos é rotacionaveis sem downtime.
• Token bucket por chave é limitador por IP para suavizar picos.
• Idempotência estilo Stripe, janela de 24 horas, reproduz a resposta armazenada.
• Cobranca por créditos: um lookup simples custa 1 credito, um deliverability score custa 25.
• Excedente cobrado no inicio de cada mes para planos pagos que ultrapassam sua cota.

URL base

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

Todas as rotas usam HTTPS. O site www.captaindns.com hospeda o dashboard é o portal de documentação, api.captaindns.com hospeda a API propriamente dita.

Inicio rapido em cinco minutos

Criar uma chave API

Faca login no dashboard CaptainDNS, abra Account > API keys, clique no botão de nova chave. Escolha um nome, um ambiente (live ou test), os escopos necessários é uma data de expiracao opcional. O segredo em texto claro é exibido apenas uma vez: copie-o para seu gerenciador de segredos antes de fechar o dialogo.

Lancar a primeira requisicao

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

A resposta contem os registros solicitados é tres familias de headers que guiam o cliente:

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

Lidar com os erros

Todos os erros compartilham o mesmo envelope JSON:

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

Os códigos mais comuns sao descritos no guia de erros. Atencao especial a RATE_LIMITED (429) é QUOTA_EXCEEDED (403): o primeiro é resolvido com backoff, o segundo exige upgrade de plano ou aguardar a proxima período.

Automatizar com idempotência

Todas as requisicoes POST aceitam o header Idempotency-Key. Qualquer reexecucao dentro de 24 horas retorna a resposta original, com X-Idempotent-Replay: true. Ideal para retries de rede no cliente. Veja o guia de idempotência.

Mapa da documentação

• Autenticação: formato da chave, allowlist de IP, rotação, revogação.
• Escopos: detalhamento de dns:read, mail:read, mail:write, web:read.
• Créditos: custo por endpoint, cotas por plano, cobranca de excedente.
• Rate limiting: token bucket por chave, backoff recomendado.
• Idempotência: reexecucoes POST, TTL 24 h, hash do corpo.
• Erros: tabela completa de códigos é ações corretivas.
• Referência OpenAPI: especificacao interativa de cada endpoint.
• Webhooks: disponíveis na V2.
• Changelog: histórico de versoes é breaking changes.

Principios operacionais

Nunca chame do navegador: seu frontend do usuario final chama seu proprio backend, que por sua vez chama a API pública CaptainDNS. É uma regra de segurança: o segredo não deve sair do seu servidor.

Observabilidade em primeiro lugar: o header X-Request-Id é retornado em toda resposta. É registrado no lado CaptainDNS é pode ser usado para abrir um ticket de suporte.

Ferramentas CaptainDNS relacionadas

Os mesmos diagnósticos estao disponíveis como ferramentas web, uteis para verificar manualmente a saida da sua integração:

• DMARC checker para comparar visualmente a policy detectada.
• SPF checker com validacao da contagem de lookups.
• DNSSEC checker com trace da cadeia a partir da raiz.
• Blacklist check agregado em mais de 90 RBLs.

Pronto para codar? Leia autenticação é passe para rate limiting antes do primeiro deploy em produção.