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

Rate limiting

Limits are applied per client (by IP or X-Forwarded-For/ 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"