API Overview - netray.info

Five tools, five base URLs, one JSON error format. All endpoints are public, rate-limited, and require no authentication.

Tool	Base URL	Reference
IP Enrichment	`https://ip.netray.info`	IP API docs
DNS Inspector	`https://dns.netray.info`	DNS API docs
TLS Inspector	`https://tls.netray.info`	TLS API docs
HTTP Inspector	`https://http.netray.info`	HTTP API docs
Email Inspector	`https://email.netray.info`	Email API docs
Lens	`https://lens.netray.info`	(see lens.netray.info — no separate API docs)

Quick Start

Get your public IP and enrichment data:

curl -s https://ip.netray.info/all/json | jq .

Look up DNS records for a domain:

curl -s -X POST https://dns.netray.info/api/query \
  -H 'Content-Type: application/json' \
  -d '{"query": "example.com A"}' \
  --no-buffer

Inspect a TLS certificate:

curl -s 'https://tls.netray.info/api/inspect?host=example.com' | jq .

Inspect HTTP security headers:

curl -s 'https://http.netray.info/api/inspect?url=https%3A%2F%2Fexample.com' | jq .

Check email security posture (SSE stream):

curl -N https://email.netray.info/inspect/example.com

Common Headers

Every response includes:

Header	Description
`X-Request-Id`	UUID v7 request identifier for debugging
`X-RateLimit-Limit`	Requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window

Rate Limits

Tool	Limit	Notes
IP	60 req/min per IP, burst 10	Applies to all endpoints
DNS	3-tier GCRA (per-IP, per-target, global)	Cost = record_types x servers
TLS	Per-IP + per-target GCRA	Cost = ports x inspected IPs
HTTP	Per-IP GCRA	Up to 3 outbound probes per request
Email	Per-IP GCRA	12 check categories per request

When rate-limited, you receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

Error Format

All five tools use the same error envelope:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 12 seconds."
  }
}

Common error codes:

HTTP Status	Code	Meaning
400	`bad_request`	Malformed input or missing required parameters
404	`not_found`	Unknown endpoint or resource
429	`rate_limited`	Rate limit exceeded; check `Retry-After` header
500	`internal_error`	Server error; include `X-Request-Id` in bug reports

CI / Pipeline Integration

All endpoints work in non-interactive contexts. Minimal GitHub Actions examples:

# Check TLS health in CI
- run: |
    curl -sf https://tls.netray.info/api/inspect?host=$DOMAIN \
      | jq -e '.quality.verdict == "Pass"'

# Verify DNS records exist
- run: |
    curl -sf -X POST 'https://dns.netray.info/api/query?stream=false' \
      -H 'Content-Type: application/json' \
      -d "{\"query\": \"$DOMAIN MX\"}" \
      | jq -e '.events | length > 0'

# Check IP reputation
- run: |
    curl -sf "https://ip.netray.info/network/json?ip=$IP" \
      | jq -e '.type == "residential"'

Interactive API Reference

Each tool also exposes auto-generated OpenAPI documentation with a try-it-out interface: