{
  "openapi": "3.0.3",
  "info": {
    "title": "IPInfo.nz API",
    "version": "1.0.0",
    "description": "Looking-Glass diagnostic toolbox. All endpoints return JSON unless explicitly text/octet-stream. Rate-limited per source IP.",
    "contact": { "name": "4U Computer Solutions", "url": "https://www.4ucs.co.nz/" }
  },
  "servers": [{ "url": "https://ipinfo.nz" }],
  "paths": {

    "/?action=ip": {
      "get": {
        "summary": "Plain-text IP",
        "description": "Returns the visitor's public IP as plain text. Default response if Accept: text/plain or User-Agent contains 'curl'. Add ?full=1 for ASN/ISP/PTR lines.",
        "responses": { "200": { "description": "OK", "content": { "text/plain": {} } } }
      }
    },
    "/?action=json": {
      "get": {
        "summary": "Snapshot JSON",
        "responses": { "200": { "description": "OK", "content": { "application/json": {} } } }
      }
    },
    "/?action=txt": {
      "get": {
        "summary": "Plain-text snapshot",
        "responses": { "200": { "description": "OK", "content": { "text/plain": {} } } }
      }
    },
    "/?action=echo": {
      "get": {
        "summary": "RTT echo",
        "responses": { "200": { "description": "OK", "content": { "application/json": {} } } }
      }
    },
    "/?action=blob": {
      "get": {
        "summary": "Bandwidth download blob",
        "parameters": [{ "in": "query", "name": "bytes", "schema": { "type": "integer", "minimum": 1024, "maximum": 52428800 }, "description": "Bytes to send (1KB – 50MB)." }],
        "responses": { "200": { "description": "Octet stream", "content": { "application/octet-stream": {} } } }
      }
    },

    "/api.php?endpoint=meta": {
      "get": { "summary": "Visitor metadata (IP, ASN, geo, UA)" }
    },
    "/api.php?endpoint=dns": {
      "get": {
        "summary": "DNS lookup",
        "parameters": [
          { "in": "query", "name": "host",  "required": true,  "schema": { "type": "string" } },
          { "in": "query", "name": "types", "required": false, "schema": { "type": "string", "default": "A,AAAA,MX,NS,TXT,CNAME,SOA,CAA" } }
        ]
      }
    },
    "/api.php?endpoint=reverse-dns": {
      "get": {
        "summary": "PTR lookup",
        "parameters": [{ "in": "query", "name": "ip", "schema": { "type": "string" }, "description": "Defaults to caller IP" }]
      }
    },
    "/api.php?endpoint=whois": {
      "get": {
        "summary": "RDAP / WHOIS",
        "parameters": [{ "in": "query", "name": "q", "required": true, "schema": { "type": "string" }, "description": "domain, IP, or AS number" }]
      }
    },
    "/api.php?endpoint=tls": {
      "get": {
        "summary": "TLS / SSL inspector",
        "parameters": [
          { "in": "query", "name": "host", "required": true,  "schema": { "type": "string" } },
          { "in": "query", "name": "port", "required": false, "schema": { "type": "integer", "default": 443 } }
        ]
      }
    },
    "/api.php?endpoint=headers": {
      "get": {
        "summary": "HTTP header inspector",
        "parameters": [{ "in": "query", "name": "url", "required": true, "schema": { "type": "string" } }]
      }
    },
    "/api.php?endpoint=port": {
      "get": {
        "summary": "TCP port check",
        "description": "Visitor's own IP only. Restricted to a configured allowlist of common ports."
      }
    },
    "/api.php?endpoint=rbl": {
      "get": {
        "summary": "DNS Blacklist (RBL) check",
        "parameters": [{ "in": "query", "name": "ip", "schema": { "type": "string" }, "description": "IPv4 only; defaults to caller" }]
      }
    },
    "/api.php?endpoint=email": {
      "get": {
        "summary": "SPF / DKIM / DMARC / MX",
        "parameters": [
          { "in": "query", "name": "domain",   "required": true,  "schema": { "type": "string" } },
          { "in": "query", "name": "selector", "required": false, "schema": { "type": "string", "default": "default" } }
        ]
      }
    },
    "/api.php?endpoint=ping": { "get": { "summary": "Server ICMP ping (gated)" } },
    "/api.php?endpoint=traceroute": { "get": { "summary": "Server traceroute (gated)" } },

    "/api.php?endpoint=upload": {
      "post": {
        "summary": "Bandwidth upload measurement",
        "description": "Body bytes are timed and discarded. Requires X-CSRF header.",
        "requestBody": { "content": { "application/octet-stream": {} } },
        "responses": { "200": { "content": { "application/json": {} } } }
      }
    }
  },

  "x-rate-limits": {
    "default": "120/min",
    "blob":    "12/min",
    "upload":  "12/min",
    "dns":     "60/min",
    "whois":   "30/min",
    "tls":     "30/min",
    "headers": "30/min",
    "port":    "20/min",
    "rbl":     "20/min",
    "email":   "30/min",
    "ping":    "10/min",
    "traceroute": "6/min"
  }
}