Response Schema

This page documents the complete JSON response schema for the /api/v1/info 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;
}

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 using Cloudflare Worker)

NetworkInfo

Information about the IP’s network/ASN.

interface NetworkInfo {
  asn: number | null;
  as_name: string | null;
  prefix: string | null;
  rir: string | null;
  country: string | null;
  org_name: 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`)
`country`	`string \| null`	Two-letter country code
`org_name`	`string \| null`	Organization name (from RIPE database)
`tor_exit`	`boolean`	Whether IP is a known Tor exit node
`vpn_or_hosting`	`boolean`	Whether IP belongs to VPN/hosting provider

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;
}

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
`datacenter`	`string \| null`	Cloudflare datacenter code (e.g., `IAD`)

These fields are populated from Cloudflare headers when running behind Cloudflare. The tls_cipher field is available when using Cloudflare Worker with X-CF-TLS-Cipher header.

ClientInfo

Information about the client making the request.

interface ClientInfo {
  user_agent: string | null;
  accept_language: string | null;
  accept_encoding: string | null;
  client_hints: ClientHints;
}

interface ClientHints {
  sec_ch_ua: string | null;
  sec_ch_ua_platform: 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
`client_hints.sec_ch_ua`	`string \| null`	Client Hints UA string
`client_hints.sec_ch_ua_platform`	`string \| null`	Client Hints platform

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;
}

Field	Type	Description
`timestamp_utc`	`string`	ISO 8601 timestamp
`region`	`string \| null`	Server region (from `CLOAKPROBE_REGION`)
`version`	`string`	CloakProbe version

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.

interface CloudflareGeoHeaders {
  cf_ipcountry?: string;
  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;
}

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",
    "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"
  },
  "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",
    "client_hints": {
      "sec_ch_ua": "\"Chromium\";v=\"120\", \"Google Chrome\";v=\"120\"",
      "sec_ch_ua_platform": "\"Windows\""
    }
  },
  "privacy": {
    "mode": "strict",
    "logs_retained": false
  },
  "server": {
    "timestamp_utc": "2024-01-15T14:30:00.123456789Z",
    "region": "eu-central",
    "version": "0.1.1"
  },
  "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"
    }
  }
}