> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buffer.lol/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Endpoint overview for buffer.lol diagnostics tools.

# 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

| Method | Path                | Purpose                  |
| ------ | ------------------- | ------------------------ |
| `POST` | `/api/tools/[slug]` | Run one diagnostics tool |

## Request body

```json theme={null}
{
  "input": "example.com"
}
```

`input` is a string. The expected format depends on the tool.

## Response envelope

Every response uses the same top-level shape:

```json theme={null}
{
  "data": {},
  "durationMs": 142,
  "requestId": "2f2fb1b9-76a0-48aa-b789-a6e76fbdd3c8"
}
```

Errors use the same envelope with `error` instead of `data`:

```json theme={null}
{
  "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

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

```json theme={null}
{
  "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                                                    |
| Address safety        | Private, local, reserved, and multicast IP addresses are rejected for outbound checks          |
| 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                                                         |
| Cross-origin requests | Browser requests with a foreign `Origin` header are rejected                                   |
| Rate limiting         | Requests are limited by client identity, tool slug, and target                                 |
| Short cache           | DNS 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](https://rdap.org/) for domain and IP registration data. ASN responses use [Team Cymru](https://www.team-cymru.org/)'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:

| Slug          | Why                                        |
| ------------- | ------------------------------------------ |
| `ping`        | ICMP ping requires raw socket permissions  |
| `packet-loss` | Packet-loss sampling requires ICMP support |
| `traceroute`  | Traceroute 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.