# DNSTrace.dev API Base URL: `https://dnstrace.dev` All responses use JSON. Successful GET responses may be cached. Clients should handle `400`, `403`, `404`, `429`, `502` and `503` responses and read the `error` property. ## Lookup verification When both Turnstile keys are configured, diagnostic endpoints require a short-lived verification session. The website completes the challenge once, validates the single-use token on the server and receives a signed, HttpOnly, SameSite cookie valid for 15 minutes. Passive connection and service-status endpoints remain available without the cookie. ```http GET /api/turnstile/status POST /api/turnstile/verify Content-Type: application/json {"token":"turnstile-response-token"} ``` Unverified diagnostic requests return `403` with `code: "turnstile_required"`. Turnstile is inactive when either key is absent, so key staging cannot accidentally lock out the site. ## DNS records ```http GET /api/dns?target=example.com&type=A ``` Supported types are `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SOA`, `CAA`, `SRV` and `PTR`. A PTR lookup requires a public IP address in `target`. ## Email security validation ```http GET /api/email-security?domain=example.com&selector=google ``` Returns a 0–100 score, grade, exact records, validation findings and recommendations for MX, SPF, DMARC, DKIM, MTA-STS, TLS-RPT and BIMI. The optional `selector` is checked before a disclosed list of common DKIM selectors. The response includes normalized `records`, structured `answers`, DNS response code, DNSSEC authenticated-data status, `source_id` and `providers_tried`. Cloudflare 1.1.1.1 is primary; Google Public DNS is an error fallback. ## RDAP ```http GET /api/rdap?target=example.com&type=domain GET /api/rdap?target=1.1.1.1&type=ip ``` The response contains the registry object and a registrar object when RDAP discovery publishes a related registrar endpoint. RDAP.org is primary. If it fails, the Worker uses IANA's official bootstrap registry to contact the authoritative RDAP service directly. ## Web, TLS and network inspection ```http GET /api/inspect?target=example.com&ip=93.184.216.34 GET /api/tls?target=example.com ``` `/api/tls` returns the certificate currently served for a public hostname independently of slower HTTP and routing checks. `/api/inspect` accepts a public hostname or IP; the optional `ip` parameter adds routing data, and `include_tls=false` avoids a duplicate live TLS request. Private and special-use addresses are rejected. ## Global DNS measurement ```http POST /api/global-dns Content-Type: application/json {"target":"example.com","type":"A"} ``` ## Caching and fair use Successful public GET responses use short edge-cache lifetimes and expose `X-DNSTrace-Cache: HIT` or `MISS`. Each connecting address is limited to 30 requests across the API per 60 seconds. Expensive live measurements are also limited to 6 requests per 60 seconds. A `429` response includes `Retry-After`. This creates a Globalping measurement across ten configured countries. It is slower and more resource-intensive than a standard DNS lookup, so cache results and request it only when distributed evidence is needed. ## Current connection ```http GET /api/my-ip ``` Returns the caller's public connection address, Cloudflare-provided edge metadata and Apple Private Relay classification when available. This is the address that reached the Worker, which may be a VPN or relay egress. ## IP privacy relay classification ```http GET /api/ip-privacy?ip=172.224.226.1 ``` Checks a public IPv4 or IPv6 address against Apple's published Private Relay egress ranges. A match identifies a relay exit address and does not reveal the original connection address. ## IP network geolocation ```http GET /api/ip-geo?ip=1.1.1.1 ``` Returns approximate public-network metadata for an IPv4 or IPv6 address. The location describes a network region and must not be treated as a device or home address. ## Certificate-transparency fallback ```http GET /api/certificates?domain=example.com ``` Returns an `issuances` array plus source attribution and provider attempts. Public history comes from crt.sh, with Cert Spotter available as an authenticated failure fallback when `CERTSPOTTER_API_KEY` is configured. Provider failures return 502 and are not cached as empty history. Live TLS remains independently available through `/api/tls`. An issuance record does not prove that the certificate is currently served. ## Subdomain discovery ```http GET /api/subdomains?domain=example.com ``` Searches public certificate-transparency records for names below the domain, then resolves the 50 most recently valid certificate names. The response distinguishes historical names from hosts that currently return an A or CNAME answer and includes source attribution. It is not a port scan or a complete inventory of private or never-certified names. ## Provider inventory ```http GET /api/providers ``` Returns every configured provider, its capabilities, documentation, access requirements and runtime status. The policy is cache-first, primary source next, and fallback only after an operational failure. Providers are not randomly rotated to evade quotas. ## OpenAPI The complete machine-readable contract is at [`/openapi.json`](https://dnstrace.dev/openapi.json).