WhoDNS API Quickstart: Your First Key, Request and Rate-Limit Read

2026-11-02 · 3 min read

Every tool on WhoDNS exists behind a JSON API with the same authentication, the same rate-limit headers and the same error shape, so learning one endpoint teaches you the whole surface. This quickstart goes from no key to a working DNS and SSL lookup in a few minutes.

1. Create a key

Register and log in, then open the API keys page and generate a key. The free tier issues self-service keys with per-minute, per-day and per-month quotas — the exact numbers are shown alongside the key. Only a SHA-256 hash of the key is stored server-side, so the generated value is displayed once: put it in your secret store immediately, because “forgot my API key” means generating a new one.

2. Authenticate

Two header styles are accepted, pick whichever your HTTP client prefers:

curl -H "X-API-Key: wd_live_yourkey" "https://whodns.ir/api/v1/dns?domain=example.com"
curl -H "Authorization: Bearer wd_live_yourkey" "https://whodns.ir/api/v1/dns?domain=example.com"

If your account configures an IP allowlist for the key, requests from unlisted addresses fail regardless of key correctness — a common first-hour stumble.

3. Call the tools

The DNS endpoint returns a deliberately compact payload — A and NS records with the resolver that answered and a scan timestamp:

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "records": { "A": ["93.184.216.34"], "NS": ["a.iana-servers.net"] },
    "resolver": "9.9.9.9",
    "scannedAt": "2026-11-02T10:14:03Z"
  }
}

The SSL endpoint fetches the live certificate for a host and returns issuer, validity dates, days remaining and SAN names — the data a certificate-expiry cron job needs.

4. Read the rate-limit headers

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and reset information. Check Remaining before deciding to fan out: a monitoring script that pauses at low remaining counts never sees a 429, and a 429 response is the only case where retrying immediately makes things worse. Back off until the reset window instead.

5. Handle the error shape

All failures — bad key, exhausted quota, invalid domain, tool error — share one structure:

{ "ok": false, "error": { "code": "rate_limited", "message": "..." } }

Branch on ok first, then on error.code; treat any HTTP-level surprise (5xx, empty body) as a retryable failure with backoff. Every response also includes an X-Request-Id header — quote it when writing to support, because it makes your specific request findable in server logs.

A minimal monitoring loop

A cron-friendly check that watches certificate expiry for one host needs no SDK and no library, only curl and a parser:

curl -s -H "X-API-Key: wd_live_yourkey" "https://whodns.ir/api/v1/ssl?domain=example.com"

The point is the shape of the client: one authenticated GET per host, a check of ok, a comparison of days-remaining against your alert threshold, and an exit code your scheduler understands. Twenty lines of shell replace a commercial expiry-monitoring subscription for a modest portfolio, and the same loop generalises to DNS watching by changing the endpoint name.

Full endpoint reference, parameter tables and an interactive playground (your key stays in your browser’s local storage and is never sent anywhere except with your own test calls) live on the API documentation page — generate a key, paste it in, and fire your first request without leaving the page.

whodns apiapi keyx-api-keybearer tokenrate limit headersapi v1 dnsapi v1 sslerror codes