API Reference

Server-backed tools call one same-origin diagnostics endpoint. Each request runs a single tool by slug and returns a small JSON envelope.

This API powers browser-based buffer.lol diagnostics only. IP Lens does not call these routes and does not expose a separate public API; its online requests go directly from the iPhone to the selected data provider, DNS resolver, or authoritative RDAP registry.

Endpoint

Method	Path	Purpose
`POST`	`/api/tools/[slug]`	Run one diagnostics tool
`GET`	`/api/tools/ping`	Return one lightweight browser-latency sample
`GET`	`/api/tools/packet-loss`	Return one lightweight connection-stability sample

The two GET routes are sampled repeatedly by their browser tools. They measure HTTPS request behavior to buffer.lol; they do not run ICMP ping or accept an arbitrary target.

Request body

{
  "input": "example.com"
}

input is a string. The expected format depends on the tool. Most tools need no other fields, but DNS Resolver Comparison and Email DNS Health accept a supported options object.

DNS resolver options

{
  "input": "example.com",
  "options": {
    "recordType": "MX"
  }
}

recordType defaults to A and must be one of A, AAAA, CNAME, MX, NS, TXT, or CAA.

Email DNS options

{
  "input": "example.com",
  "options": {
    "dkimSelector": "selector1"
  }
}

dkimSelector is optional. When provided, it is lowercased and must be a valid DNS selector of at most 253 characters. When omitted, the result explains that a selector is required to check a DKIM public key.

Response envelope

Every response uses the same top-level shape:

{
  "data": {},
  "durationMs": 142,
  "requestId": "2f2fb1b9-76a0-48aa-b789-a6e76fbdd3c8"
}

Errors use the same envelope with error instead of data:

{
  "error": "Enter a valid public hostname.",
  "durationMs": 4,
  "requestId": "2f2fb1b9-76a0-48aa-b789-a6e76fbdd3c8"
}

Available slugs

| Slug | Input | Returns | | --- | --- | | dns-lookup | Domain name | A, AAAA, MX, TXT, CNAME, NS, and SOA records | | http-headers | HTTP or HTTPS URL | Status, response time, and response headers | | ssl-checker | Hostname or host:port | TLS authorization, protocol, cipher, and certificate summary | | uptime | HTTP or HTTPS URL | Online flag, status, status text, and response time | | port-checker | host:port | TCP reachability, resolved address, and timing | | my-ip | Empty string | Public IP inferred from request headers | | ip-geolocation | Public IP address | RDAP network summary, country, and ASN data | | asn-lookup | Public IP address or ASN | Team Cymru ASN records | | whois-lookup | Domain or public IP address | RDAP registration and network summary | | redirect-checker | HTTP or HTTPS URL | Redirect chain up to eight hops | | robots-sitemap | HTTP or HTTPS URL | robots.txt preview, declared sitemaps, and sitemap.xml status | | dns-resolver-check | Domain plus optional recordType | Normalized answers and agreement status from Cloudflare, Google, Quad9, and OpenDNS | | email-dns-health | Domain plus optional dkimSelector | MX, SPF, DMARC, DKIM, MTA-STS, and TLS reporting checks with status summaries | | security-headers | HTTP or HTTPS URL | Final URL, redirect count, response headers, and individual security-control recommendations | | traceroute | Public hostname or IP address | Public hops and timings from the diagnostics worker |

Example

curl -s https://buffer.lol/api/tools/dns-lookup \
  -H 'Content-Type: application/json' \
  -d '{"input":"example.com"}'

{
  "data": {
    "domain": "example.com",
    "records": {
      "A": ["93.184.216.34"],
      "MX": []
    },
    "errors": {
      "MX": "ENODATA"
    }
  },
  "durationMs": 31,
  "requestId": "2f2fb1b9-76a0-48aa-b789-a6e76fbdd3c8"
}

Validation and limits

Rule	Details
Input length	Inputs longer than 2,048 characters are rejected
URLs	Only HTTP and HTTPS URLs are supported
Credentials	URLs with embedded credentials are rejected
Default scheme	URL tools assume `https://` when no scheme is provided
Address safety	Private, local, reserved, and multicast IP addresses are rejected, and HTTP requests are pinned to the validated address
Fetch timeout	HTTP and RDAP provider requests time out after 8 seconds
TCP timeout	Port and TLS checks time out after 7 seconds
Body size	Request bodies over 4 KiB are rejected while the body stream is read, including chunked requests
Cross-origin requests	Browser requests with a foreign `Origin` header are rejected
DNS query timeout	Public-resolver and email DNS queries use a 3-second timeout with one attempt
Rate limiting	`POST` requests are limited by client identity, tool slug, and normalized target: 15 per minute for `dns-resolver-check` and `email-dns-health`, and 30 per minute for other tools. The lightweight `GET` sampling routes allow 1,000 requests per minute by client identity and slug
Concurrency	Live diagnostics are capped per app instance by `DIAGNOSTICS_MAX_CONCURRENCY`, defaulting to 20
Short cache	DNS lookups cache for 60 seconds; resolver comparisons for 30 seconds; RDAP for 1 hour; ASN responses for 30 minutes

Rate-limited responses return 429 with Retry-After. Responses that reach rate-limit evaluation include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. When UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are configured, rate limits coordinate through Upstash; otherwise, they use an in-memory per-instance fallback.

Providers and attribution

RDAP-backed responses use rdap.org for domain and IP registration data. ASN responses use Team Cymru’s DNS-based ASN service. DNS Resolver Comparison queries the public recursive resolvers operated by Cloudflare (1.1.1.1), Google (8.8.8.8), Quad9 (9.9.9.9), and OpenDNS (208.67.222.222). RDAP and ASN upstream failures return a 502 error in the standard response envelope, while their timeouts return 504; resolver and email DNS query failures appear within their successful structured reports.

Diagnostic-specific behavior

DNS Resolver Comparison compares normalized answer sets and ignores ordering and TTL differences. A missing answer or resolver error is distinct from a conflicting answer.
Email DNS Health checks published configuration only. It does not test inbox placement, sender reputation, or complete deliverability.
HTTP Security Headers follows at most five redirects, validates every destination against the same public-address rules, and inspects the final response without retaining its body. The returned checks are recommendations, not a security grade.

Proxy IP behavior

my-ip only trusts visitor IP headers when TRUST_PROXY_HEADERS=true, when TRUSTED_PROXY_PLATFORM is set to vercel or cloudflare, or when the runtime exposes VERCEL=1 or CF_PAGES=1. In trusted mode, header precedence is:

cf-connecting-ip
x-real-ip
the first value in x-forwarded-for

When proxy headers are not trusted, my-ip returns an unavailable state instead of echoing spoofable headers.

Browser connection tools

ping and packet-loss are retained as route slugs for compatibility, but the public tools use repeated same-origin GET requests rather than worker-backed ICMP commands:

Slug	Public behavior
`ping`	Browser Latency Test; six HTTPS round-trip samples to buffer.lol
`packet-loss`	Connection Stability Test; twenty HTTPS samples and failed-request counting

Worker-backed traceroute

POST /api/tools/traceroute requires ENABLE_WORKER_TOOLS=true, a configured DIAGNOSTICS_WORKER_URL, and a non-empty DIAGNOSTICS_WORKER_TOKEN. The Next.js route proxies the validated target to POST /api/traceroute on the restricted worker and sends the token as a bearer credential. The worker refuses to start in production without its token. Private infrastructure hop addresses and raw traceroute output are excluded by default. Operators may set INCLUDE_RAW_DIAGNOSTICS=true only when they intentionally want raw output.

Authentication

No authentication is required for the public same-origin API.

Getting Started

IP Lens

Concepts

API Reference

API Reference

API Reference

Endpoint

Request body

DNS resolver options

Email DNS options

Response envelope

Available slugs

Example

Validation and limits

Providers and attribution

Diagnostic-specific behavior

Proxy IP behavior

Browser connection tools

Worker-backed traceroute

Authentication

​API Reference

​Endpoint

​Request body

​DNS resolver options

​Email DNS options

​Response envelope

​Available slugs

​Example

​Validation and limits

​Providers and attribution

​Diagnostic-specific behavior

​Proxy IP behavior

​Browser connection tools

​Worker-backed traceroute

​Authentication

API Reference

Endpoint

Request body

DNS resolver options

Email DNS options

Response envelope

Available slugs

Example

Validation and limits

Providers and attribution

Diagnostic-specific behavior

Proxy IP behavior

Browser connection tools

Worker-backed traceroute

Authentication