API

Endpoint

GET /api/lookup

Returns JSON. All responses include the requested host and type so the payload is self-contained.

Query parameters

hostrequired

Hostname to look up (e.g. example.com). Must be a valid DNS name (labels, length, character set).

typeoptional, default A

Record type. One of: A, AAAA, ANAME, CAA, CNAME, MX, NAPTR, NS, PTR, SOA, SRV, TXT.

provideroptional, default cloudflare

Resolver: cloudflare, google, quad9, mullvad, or controld. Resolution uses RFC 8484 DoH or DoT wire format depending on transport.

transportoptional, default doh

doh (DNS over HTTPS) or dot (DNS over TLS). DoT is only available for cloudflare, google, and quad9.

Response

Success (200)

{
  "ok": true,
  "host": "example.com",
  "type": "A",
  "records": ["93.184.216.34"],
  "ttls": [3600],
  "authority": null,
  "additional": null
}

records and ttls are parallel arrays (same order). authority and additional are present when the DNS response included those sections; otherwise null.

Error (200 with ok: false or 400)

{ "ok": false, "host": "example.com", "type": "A", "error": "NXDOMAIN", "authority": { "records": ["..."], "ttls": [900] }, "additional": null }

For DNS errors (e.g. NXDOMAIN), authority and additional may be included when the resolver returned them. For invalid input, the API returns 400 with e.g. { "ok": false, "error": "invalid_host" }.

Compare endpoint

GET /api/compare

Runs lookups across all 5 resolvers in parallel and returns a combined result. Useful for DNS propagation checks.

hostrequired

Hostname to look up.

typeoptional, default A

Record type (same set as /api/lookup).

transportoptional, default doh

doh or dot. For DoT, Mullvad and Control D are skipped (returned as errors in their result entry).

{
  "host": "example.com",
  "type": "A",
  "allAgree": true,
  "results": [
    {
      "provider": "cloudflare",
      "label": "Cloudflare",
      "durationMs": 42,
      "result": { "ok": true, "host": "example.com", "type": "A", "records": ["93.184.216.34"], "ttls": [3600] }
    },
    ...
  ]
}

allAgree is true when all 5 providers returned the same records. Counts as one request against the rate limit.

Rate limiting

/ X-Real-IP when behind a proxy). Default: 60 requests per minute. When exceeded, the API returns 429 with { "ok": false, "error": "rate_limit_exceeded" } and a Retry-After header (seconds).

Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp).

Examples

# Basic A record
curl "https://your-domain.com/api/lookup?host=example.com&type=A"

# With provider and transport
curl "https://your-domain.com/api/lookup?host=example.com&type=A&provider=google"
curl "https://your-domain.com/api/lookup?host=example.com&type=A&provider=cloudflare&transport=dot"

# MX records
curl "https://your-domain.com/api/lookup?host=example.com&type=MX"