Response Schema

This page documents the complete JSON response schema for the /api/v1/json endpoint.

Full Schema

interface InfoResponse {
  ip: string;
  ip_version: number;
  reverse_dns: string | null;
  network: NetworkInfo;
  connection: ConnectionInfo;
  client: ClientInfo;
  privacy: PrivacyInfo;
  server: ServerInfo;
  cloudflare?: CloudflareHeaders;
  nginx?: NginxHeaders;
}

---

Root Fields

Field	Type	Description
ip	string	The detected IP address
ip_version	number	IP version (4 or 6)
reverse_dns	string | null	Reverse DNS lookup (always null - reverse DNS is client-side only via HTML UI)
cloudflare	CloudflareHeaders | undefined	Cloudflare Worker headers (only present when mode = "cloudflare")
nginx	NginxHeaders | undefined	Nginx headers (only present when mode = "nginx")

---

NetworkInfo

Information about the IP’s network/ASN and organization details from all 5 Regional Internet Registries.

interface NetworkInfo {
  asn: number | null;
  as_name: string | null;
  prefix: string | null;
  rir: string | null;
  country: string | null;
  org_name: string | null;
  org_id: string | null;
  org_rir: string | null;
  org_country: string | null; // Deprecated: duplicates country field
  org_type: string | null;
  abuse_contact: string | null;
  org_last_updated: string | null;
  tor_exit: boolean;
  vpn_or_hosting: boolean;
}

Field	Type	Description
asn	number | null	Autonomous System Number
as_name	string | null	AS description/name
prefix	string | null	Network prefix (CIDR notation)
rir	string | null	Regional Internet Registry (ARIN, RIPE, APNIC, LACNIC, AFRINIC) - displays org_rir value
country	string | null	Two-letter country code (from ASN database)
org_name	string | null	Organization name
org_id	string | null	Organization identifier (e.g., ORG-GVMT1-RIPE)
org_rir	string | null	RIR that provided the organization data
org_country	string | null	Deprecated: Duplicates country field. Use country instead.
org_type	string | null	Organization type (LIR, ISP, CORP, etc.)
abuse_contact	string | null	Abuse contact email address (resolved from RIR handles)
org_last_updated	string | null	Last update date of organization record
tor_exit	boolean	Whether IP is a known Tor exit node
vpn_or_hosting	boolean	Whether IP belongs to VPN/hosting provider

Note

tor_exit and vpn_or_hosting are currently always false. These fields are reserved for future detection capabilities.

---

ConnectionInfo

Information about the current connection.

interface ConnectionInfo {
  tls_version: string | null;
  http_protocol: string | null;
  tls_cipher: string | null;
  cf_ray: string | null;
  datacenter: string | null;
  request_id: string | null;
  remote_port: string | null;
  connection_id: string | null;
}

Field	Type	Description
tls_version	string | null	TLS version (e.g., TLSv1.3)
http_protocol	string | null	HTTP version (h2, http/1.1)
tls_cipher	string | null	TLS cipher suite (e.g., AEAD-AES128-GCM-SHA256)
cf_ray	string | null	Cloudflare Ray ID (only in cloudflare mode)
datacenter	string | null	Cloudflare datacenter code (e.g., IAD, only in cloudflare mode)
request_id	string | null	Unique request identifier from nginx $request_id (only in nginx mode)
remote_port	string | null	Client source port from nginx $remote_port (only in nginx mode)
connection_id	string | null	Connection serial number from nginx $connection (only in nginx mode)

These fields are populated based on the proxy mode:

• Cloudflare mode: Uses X-CF-TLS-Version, X-CF-TLS-Cipher, X-CF-HTTP-Protocol headers. cf_ray and datacenter are populated from Cloudflare headers.
• Nginx mode: Uses X-TLS-Version, X-TLS-Cipher, X-HTTP-Protocol headers. request_id, remote_port, and connection_id are populated from nginx variables.

---

ClientInfo

Information about the client making the request, including privacy preferences and security headers.

interface ClientInfo {
  user_agent: string | null;
  accept_language: string | null;
  accept_encoding: string | null;
  dnt: string | null;
  sec_gpc: string | null;
  save_data: string | null;
  upgrade_insecure_requests: string | null;
  referer: string | null;
  origin: string | null;
  client_hints: ClientHints;
  sec_fetch: SecFetchHeaders;
}

interface ClientHints {
  sec_ch_ua: string | null;
  sec_ch_ua_platform: string | null;
  sec_ch_ua_mobile: string | null;
  sec_ch_ua_full_version_list: string | null;
  device_memory: string | null;
  viewport_width: string | null;
  downlink: string | null;
  rtt: string | null;
  ect: string | null;
}

interface SecFetchHeaders {
  site: string | null;
  mode: string | null;
  dest: string | null;
  user: string | null;
}

Field	Type	Description
user_agent	string | null	User-Agent header value
accept_language	string | null	Accept-Language header
accept_encoding	string | null	Accept-Encoding header
dnt	string | null	Do Not Track preference (Enabled / Disabled)
sec_gpc	string | null	Global Privacy Control (Enabled / Disabled)
save_data	string | null	Save-Data preference
upgrade_insecure_requests	string | null	HTTPS upgrade preference
referer	string | null	Referer header
origin	string | null	Origin header
client_hints.sec_ch_ua	string | null	Client Hints UA string
client_hints.sec_ch_ua_platform	string | null	Client Hints platform
client_hints.sec_ch_ua_mobile	string | null	Mobile device indicator
client_hints.sec_ch_ua_full_version_list	string | null	Full version list
client_hints.device_memory	string | null	Device memory (GB)
client_hints.viewport_width	string | null	Viewport width (px)
client_hints.downlink	string | null	Network downlink (Mbps)
client_hints.rtt	string | null	Network RTT (ms)
client_hints.ect	string | null	Effective connection type
sec_fetch.site	string | null	Sec-Fetch-Site header
sec_fetch.mode	string | null	Sec-Fetch-Mode header
sec_fetch.dest	string | null	Sec-Fetch-Dest header
sec_fetch.user	string | null	Sec-Fetch-User header

---

PrivacyInfo

Information about the server’s privacy mode.

interface PrivacyInfo {
  mode: string;
  logs_retained: boolean;
}

Field	Type	Description
mode	string	Privacy mode (strict or balanced)
logs_retained	boolean	Whether logs are retained

---

ServerInfo

Information about the CloakProbe server.

interface ServerInfo {
  timestamp_utc: string;
  region: string | null;
  version: string;
  response_time_ms: number | null;
}

Field	Type	Description
timestamp_utc	string	ISO 8601 timestamp
region	string | null	Server region (from CLOAKPROBE_REGION)
version	string	CloakProbe version
response_time_ms	number | null	Server processing time in milliseconds

---

CloudflareHeaders

Information from Cloudflare Worker headers (only present when using Cloudflare Worker).

interface CloudflareHeaders {
  geo?: CloudflareGeoHeaders;
  network?: CloudflareNetworkHeaders;
  connection?: CloudflareConnectionHeaders;
  security?: CloudflareSecurityHeaders;
  proxy?: CloudflareProxyHeaders;
}

CloudflareGeoHeaders

Geographic location information (derived from CF-IPCountry header).

interface CloudflareGeoHeaders {
  country?: string;
  city?: string;
  region?: string;
  region_code?: string;
  continent?: string;
  latitude?: string;
  longitude?: string;
  postal_code?: string;
  timezone?: string;
}

CloudflareNetworkHeaders

Network information.

interface CloudflareNetworkHeaders {
  asn?: string;
  as_organization?: string;
  colo?: string;
}

CloudflareConnectionHeaders

Connection details.

interface CloudflareConnectionHeaders {
  cf_visitor?: string;
  x_forwarded_proto?: string;
  http_protocol?: string;
  tls_version?: string;
  tls_cipher?: string;
  cf_request_id?: string;
  cf_cache_status?: string;
}

CloudflareSecurityHeaders

Security and bot management information.

interface CloudflareSecurityHeaders {
  trust_score?: string;
  bot_score?: string;
  verified_bot?: string;
}

CloudflareProxyHeaders

Proxy forwarding headers.

interface CloudflareProxyHeaders {
  x_forwarded_for?: string;
  x_real_ip?: string;
}

---

NginxHeaders

Information from nginx headers (only present when mode = "nginx").

interface NginxHeaders {
  geo?: NginxGeoHeaders;
  proxy?: CloudflareProxyHeaders;
}

NginxGeoHeaders

Geographic location information from nginx GeoIP module (optional, requires GeoIP module configuration).

interface NginxGeoHeaders {
  country?: string;
  city?: string;
  region?: string;
  latitude?: string;
  longitude?: string;
  postal_code?: string;
  org?: string;
}

Field	Type	Description
country	string | undefined	Two-letter country code from GeoIP
city	string | undefined	City name from GeoIP
region	string | undefined	Region/state name from GeoIP
latitude	string | undefined	Latitude coordinate
longitude	string | undefined	Longitude coordinate
postal_code	string | undefined	Postal/ZIP code
org	string | undefined	Organization/ISP name from GeoIP

Note

GeoIP headers require nginx to be configured with the GeoIP module (ngx_http_geoip_module or ngx_http_geoip2_module). See the Nginx Deployment Guide for setup instructions.

---

Example Response

{
  "ip": "2001:db8::1234",
  "ip_version": 6,
  "reverse_dns": null,
  "network": {
    "asn": 64496,
    "as_name": "EXAMPLE-NET",
    "prefix": "2001:db8::/32",
    "rir": "RIPE",
    "country": "DE",
    "org_name": "Example GmbH",
    "org_id": "ORG-EG1-RIPE",
    "org_rir": "ripe",
    "org_country": "DE",
    "org_type": "LIR",
    "abuse_contact": "abuse@example.de",
    "org_last_updated": "2024-01-10",
    "tor_exit": false,
    "vpn_or_hosting": false
  },
  "connection": {
    "tls_version": "TLSv1.3",
    "http_protocol": "h2",
    "tls_cipher": "AEAD-AES128-GCM-SHA256",
    "cf_ray": "8abc123def456-FRA",
    "datacenter": "FRA",
    "request_id": null,
    "remote_port": null,
    "connection_id": null
  },
  "client": {
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "accept_language": "en-US,en;q=0.9,de;q=0.8",
    "accept_encoding": "gzip, deflate, br",
    "dnt": "Enabled",
    "sec_gpc": "Enabled",
    "save_data": null,
    "upgrade_insecure_requests": "1",
    "referer": null,
    "origin": null,
    "client_hints": {
      "sec_ch_ua": "\"Chromium\";v=\"120\", \"Google Chrome\";v=\"120\"",
      "sec_ch_ua_platform": "\"Windows\"",
      "sec_ch_ua_mobile": "?0",
      "sec_ch_ua_full_version_list": null,
      "device_memory": "8",
      "viewport_width": "1920",
      "downlink": null,
      "rtt": null,
      "ect": null
    },
    "sec_fetch": {
      "site": "none",
      "mode": "navigate",
      "dest": "document",
      "user": "?1"
    }
  },
  "privacy": {
    "mode": "strict",
    "logs_retained": false
  },
  "server": {
    "timestamp_utc": "2024-01-15T14:30:00.123456789Z",
    "region": "eu-central",
    "version": "0.1.3",
    "response_time_ms": 0.42
  },
  "cloudflare": {
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "region": "Berlin",
      "region_code": "BE",
      "continent": "EU",
      "latitude": "52.5200",
      "longitude": "13.4050",
      "postal_code": "10115",
      "timezone": "Europe/Berlin"
    },
    "network": {
      "asn": "AS64496",
      "as_organization": "Example GmbH",
      "colo": "FRA"
    },
    "connection": {
      "http_protocol": "h2",
      "tls_version": "TLSv1.3",
      "tls_cipher": "AEAD-AES128-GCM-SHA256",
      "cf_request_id": "8abc123def456",
      "cf_cache_status": "MISS"
    },
    "security": {
      "trust_score": "50",
      "bot_score": "1",
      "verified_bot": "false"
    }
  }
}