DNS Lens
API v1
Operational

DNS Lens Public API

DNS records, domain registration, global propagation and health insights as predictable JSON. No account or API key required.

Quick start

Base URL

https://your-domain.example/api/public/v1

Authentication

None required

Format

JSON over HTTPS

cURL
curl --request GET \
  --url 'https://your-domain.example/api/public/v1/dns?domain=example.com&type=A' \
  --header 'accept: application/json'

CORS is enabled for browser use. All endpoints are read-only and accept GET requests; OPTIONS is available for preflight checks.

Fair-use rate limits

Each endpoint has an independent rolling 60-second budget per IP. Repeated bursts trigger progressively longer temporary blocks; normal use for one hour clears the strike history.

1st breach

30 seconds

2nd breach

2 minutes

3rd breach

10 minutes

4th breach

30 minutes

5th breach

1 hour

6th+ breach

3 hours

Retry-After seconds until retry

X-RateLimit-Limit total budget

X-RateLimit-Remaining calls left

Reference

Endpoints

Change the test domain once, then run any request below. Its response stays with that endpoint.

GET
/api/public/v1/dns30 req / min

Resolve DNS records

Resolve one record type or request a complete batch. ALL responses also include a DNS health score based on DNSSEC, TTLs, nameserver coverage and email authentication.

Query parameters

domain
stringrequired
A valid hostname, without a protocol or path.
type
enumdefault: A
The DNS record set to return.A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV, CAA, ALL
resolver
enumdefault: cloudflare
The upstream resolver used for the lookup.cloudflare, google, adguard

Behavior notes

  • type=ALL runs the supported record queries as one batch.
  • An empty answers array is a valid response when the record does not exist.
  • ms is the upstream resolver response time, rounded to milliseconds.
Request
curl "https://your-domain.example/api/public/v1/dns?domain=mdjhs.com&type=ALL&resolver=cloudflare"
Example success response
200 JSON
{
  "ok": true,
  "domain": "mdjhs.com",
  "resolver": "cloudflare",
  "queriedAt": "2026-09-14T02:50:00.000Z",
  "records": [
    {
      "type": "A",
      "ms": 42,
      "status": "NOERROR",
      "dnssec": false,
      "answers": [
        { "name": "mdjhs.com", "type": "A", "ttl": 300, "data": "46.247.90.193" }
      ]
    }
  ],
  "health": { "score": 78, "grade": "B" }
}
Runs with mdjhs.com
GET
/api/public/v1/whois15 req / min

Read domain registration data

Returns the best available RDAP and WHOIS registration record, including registrar, dates, statuses, nameservers and public contact blocks.

Query parameters

domain
stringrequired
The registered domain to inspect, such as example.com.

Behavior notes

  • Private or redacted contacts are omitted rather than returned as empty objects.
  • Dates are returned as supplied by the registry and are normally ISO 8601.
  • A registry may publish only a subset of registration fields.
Request
curl "https://your-domain.example/api/public/v1/whois?domain=mdjhs.com"
Example success response
200 JSON
{
  "ok": true,
  "queriedAt": "2026-09-14T02:50:00.000Z",
  "whois": {
    "domain": "mdjhs.com",
    "registrar": "Spaceship, Inc.",
    "registered": "2024-01-01T00:00:00Z",
    "expires": "2027-01-01T00:00:00Z",
    "nameservers": ["ns1.stackdns.com"],
    "source": "RDAP + WHOIS"
  }
}
Runs with mdjhs.com
GET
/api/public/v1/propagation5 req / min

Check global DNS propagation

Queries real probes across thirteen regions and compares every answer with the majority result. This request can take longer than a normal DNS lookup.

Query parameters

domain
stringrequired
The hostname to check from all probe locations.
type
enumdefault: A
The record type queried by every probe.A, AAAA, CNAME, MX, TXT, NS, SOA, SRV, CAA

Behavior notes

  • status is match, different or error for each probe.
  • The consensus field contains the most common normalized answer.
  • Probe availability can vary, so the returned location count may change.
Request
curl "https://your-domain.example/api/public/v1/propagation?domain=mdjhs.com&type=A"
Example success response
200 JSON
{
  "ok": true,
  "queriedAt": "2026-09-14T02:50:00.000Z",
  "propagation": {
    "domain": "mdjhs.com",
    "type": "A",
    "consensus": ["46.247.90.193"],
    "locations": [
      { "country": "US", "city": "New York", "status": "match", "answers": ["46.247.90.193"] }
    ]
  }
}
Runs with mdjhs.com
GET
/api/public/v1/report8 req / min

Generate a complete domain report

Combines the full DNS record batch, SPF/DMARC/DKIM checks, DNS health scoring and optional WHOIS data in one response.

Query parameters

domain
stringrequired
The domain used throughout the report.
resolver
enumdefault: cloudflare
The upstream resolver used for DNS records.cloudflare, google, adguard
whois
booleandefault: true
Set to false when registration data is not needed.true, false

Behavior notes

  • Use whois=false for a faster DNS-only report.
  • Email authentication checks include SPF, DMARC and common DKIM selectors.
  • A WHOIS failure does not prevent the DNS portion from being returned.
Request
curl "https://your-domain.example/api/public/v1/report?domain=mdjhs.com&resolver=cloudflare&whois=true"
Example success response
200 JSON
{
  "ok": true,
  "domain": "mdjhs.com",
  "resolver": "cloudflare",
  "queriedAt": "2026-09-14T02:50:00.000Z",
  "health": { "score": 78, "grade": "B" },
  "records": [],
  "whois": { "domain": "mdjhs.com", "source": "RDAP + WHOIS" }
}
Runs with mdjhs.com
GET
/api/public/v1/status

Inspect your current rate-limit budget

Shows the remaining request budget for the caller's IP on every endpoint and reports any active temporary block.

Query parameters

No query parameters.

Behavior notes

  • The status endpoint does not consume a lookup budget.
  • Budgets are isolated by endpoint and calculated per caller IP.
Request
curl "https://your-domain.example/api/public/v1/status"
Example success response
200 JSON
{
  "ok": true,
  "service": "DNS Lens API",
  "version": "1",
  "windowSeconds": 60,
  "endpoints": {
    "dns": { "limit": 30, "remaining": 29, "blocked": false },
    "whois": { "limit": 15, "remaining": 15, "blocked": false }
  }
}
Runs with mdjhs.com

Errors

Every failure uses the same envelope. Branch on error.code, not the human-readable message, and use the HTTP status for retry decisions.

400
INVALID_DOMAIN

The domain is missing or malformed.

Send a hostname such as example.com, without https:// or a path.

400
INVALID_RECORD_TYPE

The requested DNS record type is unsupported.

Use one of the values documented for that endpoint.

400
INVALID_RESOLVER

The resolver name is not recognized.

Use cloudflare, google, or adguard.

429
RATE_LIMITED

This IP exceeded its rolling request budget.

Read Retry-After, wait that many seconds, then retry once.

502
WHOIS_LOOKUP_FAILED

Registration sources did not return usable data.

The registry may be unavailable or hold no public record. Retry later.

502
PROPAGATION_CHECK_FAILED

Global probes could not finish the measurement.

Retry shortly or use a different record type.

Error envelope
{
  "ok": false,
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Provide a valid ?domain= value",
    "status": 400
  },
  "timestamp": "2026-09-14T02:50:00.000Z",
  "docs": "/api-docs#errors"
}

Retry 429 responses only after Retry-After. For temporary 502 responses, use exponential backoff and stop after a small number of attempts.