Documentación de la API pública de CaptainDNS

Quieres consultar los diagnósticos DNS, correo y web de CaptainDNS desde tu propio stack? La API pública expone 40+ endpoints cuidadosamente seleccionados, protegidos por clave y medidos en créditos. Esta guia te lleva desde el primer curl hasta una integración lista para producción.

Que obtienes

• 40+ endpoints seleccionados: resolución DNS, verificación SPF/DKIM/DMARC/BIMI/MTA-STS/TLS-RPT, blacklist, SMTP, deliverability, URL check, page crawl y detección de phishing.
• Claves API en formato cdns_live_... y cdns_test_..., cada una con scopes y rotables sin interrupción.
• Token bucket por clave y limitador por IP para suavizar picos.
• Idempotencia estilo Stripe, ventana de 24 horas, reproduce la respuesta almacenada.
• Medicion por créditos: un lookup simple cuesta 1 credito, un deliverability score cuesta 25.
• Overage facturado cada inicio de mes para los planes de pago que exceden su cupo.

URL base

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

Todas las rutas usan HTTPS. El sitio www.captaindns.com aloja el dashboard y el portal de documentación, api.captaindns.com aloja la API propiamente dicha.

Inicio rapido en cinco minutos

Crear una clave API

Inicia sesión en el dashboard de CaptainDNS, abre Account > API keys, haz clic en el boton de nueva clave. Elige un nombre, un entorno (live o test), los scopes necesarios y una fecha de expiración opcional. El secreto en claro se muestra una unica vez: copialo a tu gestor de secretos antes de cerrar el dialogo.

Lanzar la primera peticion

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 respuesta contiene los registros solicitados y tres familias de cabeceras que guian al 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

Gestionar los errores

Todos los errores comparten la misma envoltura JSON:

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

Los códigos mas frecuentes se describen en la guia de errores. Presta atencion a RATE_LIMITED (429) y QUOTA_EXCEEDED (403): el primero se resuelve con backoff, el segundo requiere cambiar de plan o esperar al mes siguiente.

Automatizar con idempotencia

Todas las peticiones POST aceptan una cabecera Idempotency-Key. Cualquier reintento identico en un plazo de 24 horas devuelve la respuesta original, con X-Idempotent-Replay: true. Ideal para reintentos de red en el cliente. Consulta la guia de idempotencia.

Mapa de la documentación

• Autenticación: formato de clave, allowlist de IP, rotación, revocación.
• Scopes: desglose de dns:read, mail:read, mail:write, web:read.
• Créditos: coste por endpoint, cupos por plan, overage.
• Rate limiting: token bucket por clave, backoff recomendado.
• Idempotencia: reintentos POST, TTL de 24 h, hash del cuerpo.
• Errores: tabla completa de códigos y acciones correctivas.
• Referencia OpenAPI: especificacion interactiva de cada endpoint.
• Webhooks: disponibles en V2.
• Changelog: historial de versiones y breaking changes.

Principios operativos

Nunca llames desde el navegador: tu frontend llama a tu propio backend, que a su vez invoca la API pública de CaptainDNS. Es una regla de seguridad: el secreto no debe abandonar tu servidor.

Observabilidad en primer lugar: la cabecera X-Request-Id se devuelve en cada respuesta. Se registra en CaptainDNS y sirve para abrir un ticket de soporte si algo falla.

Herramientas CaptainDNS relacionadas

Los mismos diagnósticos estan disponibles como herramientas web, utiles para verificar manualmente el resultado de tu integración:

• Verificación DMARC para comparar visualmente la politica detectada.
• Chequeo SPF con validacion del número de lookups.
• Verificación DNSSEC con traza de la cadena desde la raiz.
• Blacklist check agregado sobre mas de 90 RBL.

Listo para programar? Lee autenticación y pasa a rate limiting antes de tu primer despliegue en producción.