Skip to main content

​
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.

​
Endpoint

MethodPathPurpose
POST/api/tools/[slug]Run one diagnostics tool

​
Request body

{
  "input": "example.com"
}
input is a string. The expected format depends on the tool.

​
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 |

​
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

RuleDetails
Input lengthInputs longer than 2,048 characters are rejected
URLsOnly HTTP and HTTPS URLs are supported
CredentialsURLs with embedded credentials are rejected
Address safetyPrivate, local, reserved, and multicast IP addresses are rejected for outbound checks
Fetch timeoutHTTP and RDAP provider requests time out after 8 seconds
TCP timeoutPort and TLS checks time out after 7 seconds
Body sizeRequest bodies over 4 KiB are rejected
Cross-origin requestsBrowser requests with a foreign Origin header are rejected
Rate limitingRequests are limited by client identity, tool slug, and target
Short cacheDNS responses cache for 60 seconds; RDAP caches for 1 hour; ASN responses cache for 30 minutes

​
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. Provider outages return a 502 error in the standard response envelope, while timeouts return 504.

​
Proxy IP behavior

my-ip only trusts visitor IP headers when TRUST_PROXY_HEADERS=true, or when TRUSTED_PROXY_PLATFORM is set to vercel, netlify, or cloudflare. In trusted mode, header precedence is:
  1. cf-connecting-ip
  2. x-real-ip
  3. the first value in x-forwarded-for
When proxy headers are not trusted, my-ip returns an unavailable state instead of echoing spoofable headers.

​
Worker-required tools

These slugs exist in the product catalog but return a friendly 501 disabled response from the shared API until ENABLE_WORKER_TOOLS=true and DIAGNOSTICS_WORKER_URL point to a healthy container or VM worker:
SlugWhy
pingICMP ping requires raw socket permissions
packet-lossPacket-loss sampling requires ICMP support
tracerouteTraceroute requires traceroute privileges
When the worker is enabled, the public API remains POST /api/tools/[slug]; the Next.js route proxies internally to worker endpoints such as POST /api/ping.

​
Authentication

No authentication is required.