HetOps DNS API

Programmatic domain intelligence over a simple JSON API — DNS, WHOIS, SSL/TLS, security headers, DNSSEC, global propagation, GeoIP, ports, email authentication and more. Free, no key required for normal use.

Basics

All analysis endpoints accept POST with a JSON body { "domain": "example.com" } and return JSON. Base URL: https://dns.hetops.dev.

curl -X POST https://dns.hetops.dev/api/dns-lookup \
  -H "Content-Type: application/json" \
  -d '{"domain":"github.com"}'

Aggregate scan

One call that runs the core checks and returns the overall health summary — built for scripts and CI pipelines. Optional checks array narrows the run.

curl -X POST https://dns.hetops.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"domain":"github.com"}'

// response shape
{
  "domain": "github.com",
  "durationMs": 4200,
  "checks": ["dns-lookup", "ssl", "email-security", "blacklist-check", "whois"],
  "results": { "dns-lookup": { ... }, "ssl": { ... }, ... },
  "summary": { "pct": 92, "grade": "A", "breakdown": [ ... ] }
}

Available checks values: dns-lookup, ssl, email-security, blacklist-check, whois. The summary uses the same weighting as the app's health score and the badge (DNS hygiene 50 · email 20 · TLS 30 · blacklist 10). A check that fails returns { "error": "..." } in its slot without failing the whole scan.

API keys

Keys are optional — they give you a dedicated, much larger quota instead of the shared per-IP limit. Create one from the app (sign in → your account → API keys), then pass it as a header:

-H "X-API-Key: hk_xxxxxxxxxxxx"

Rate limits

Without a key: shared per-IP limit (generous — about 20 full analyses/minute). With a valid X-API-Key: a per-key quota roughly 4× the anonymous limit. Responses are cached server-side (~5 min) so repeat lookups are instant and don't count against limits. Requests to private/internal addresses are rejected (403).

Endpoints

Every endpoint below is POST with body { "domain": "<host>" } unless noted.

Core

Path	Returns
/api/scan	Aggregate: core checks + health summary (see above)
/api/dns-lookup	A/AAAA/MX/TXT/NS/CNAME/SOA/CAA/SRV/PTR records + insights. Also accepts domains (array, ≤20), types, resolver, compareAuthoritative, discoverSubdomains
/api/whois	Registration data — RDAP first with WHOIS fallback; includes structured expiresAt when available
/api/geoip	IP geolocation & network info
/api/propagation	Global DNS propagation across resolvers. Accepts type

Security

Path	Returns
/api/ssl	Certificate, chain, protocols, ciphers, vulnerabilities, grade
/api/ssl-labs	SSL-Labs-style grade only
/api/security-headers	HTTP security header analysis & score
/api/csp-analyzer	Content-Security-Policy directive analysis & grade
/api/dnssec	DNSSEC configuration
/api/dnssec-chain	Full DNSSEC chain of trust (root → TLD → zone)
/api/ocsp	OCSP stapling & revocation status
/api/hsts-preload	HSTS preload eligibility
/api/subdomain-takeover	Dangling-CNAME takeover checks
/api/blacklist-check	DNSBL reputation across major lists

Email

Path	Returns
/api/email-security	SPF, DKIM, DMARC, BIMI analysis & score. Accepts selectors (array, ≤20 extra DKIM selectors)
/api/mx-smtp	MX topology & SMTP banner/TLS analysis
/api/mta-sts	MTA-STS policy & DANE/TLSA

Network & web

Path	Returns
/api/ipv6	IPv4/IPv6 dual-stack & reachability
/api/trace	Traceroute-style path analysis
/api/port-scan	Port reachability. Accepts ports (array, ≤30)
/api/http	HTTP/2/3, compression, features & score
/api/redirect	Redirect chain trace
/api/tech	Technology / stack fingerprinting
/api/cors	CORS policy analysis
/api/cookies	Cookie security flags
/api/robots	robots.txt & sitemap
/api/sshfp	SSHFP records

Intelligence

Path	Returns
/api/cert-transparency	Certificate Transparency log entries
/api/typosquat	Registered look-alike domains

Account (session cookie required)

Path	Purpose
POST /api/auth/request	Email a magic sign-in link — body { "email": "you@example.com" }
GET /api/auth/me	Current session info
GET|POST|DELETE /api/history	Scan history sync
GET|POST /api/alerts, DELETE /api/alerts/:domain	Monitoring watchlist (≤50 domains)
GET|POST /api/settings	Webhook URL & weekly digest
GET|POST /api/keys, DELETE /api/keys/:key	API key management (≤10 keys)

Status badge

Embed a live security-grade badge in your README — it recomputes on each load:

GET /api/badge/<domain>.svg

[![HetOps DNS](https://dns.hetops.dev/api/badge/github.com.svg)](https://dns.hetops.dev/?domain=github.com)

Errors

Errors return a JSON body { "error": "message" } with an appropriate status: 400 invalid domain, 403 blocked/internal host, 429 rate limited, 500 lookup failed.