Response Schema

Canonical v1 Response Example

The v1 API returns IPBot-owned intelligence fields. Public responses do not expose internal data source names, data package versions, raw rule identifiers, or runtime metadata.

{
  "ip": "2001:4860:4860::8888",
  "stack": "ipv6",
  "location": {
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "city": "Mountain View",
    "latitude": 37.3861,
    "longitude": -122.0838,
    "timezone": "-08:00"
  },
  "network": {
    "asn": "AS15169",
    "org": "GOOGLE",
    "category": "internet_infrastructure",
    "operator": "Google",
    "operator_type": "cloud",
    "service_role": "public_dns_resolver",
    "service_name": "Google Public DNS",
    "routability": "global",
    "owner": "Google LLC",
    "allocation": {
      "cidr": "2001:4860:4860::/48",
      "range": "2001:4860:4860:: - 2001:4860:4860:ffff:ffff:ffff:ffff:ffff",
      "registry": "arin",
      "country": "US"
    }
  },
  "routing": {
    "origin_asn": "AS15169",
    "prefix": "2001:4860:4860::/48",
    "rpki_status": "valid",
    "confidence": "high",
    "origin_conflict": false
  },
  "score": {
    "ip_score": 70,
    "risk_score": 30,
    "band": "good",
    "verdict": "allow",
    "recommended_action": "allow"
  },
  "classification": {
    "usage_type": "public_dns_resolver",
    "is_datacenter": false,
    "is_proxy": false,
    "service_role": "public_dns_resolver",
    "service_name": "Google Public DNS",
    "is_public_resolver": true,
    "is_anycast": true,
    "is_special_use": false,
    "is_bogon": false,
    "is_privacy_relay": false,
    "is_known_crawler": false,
    "is_verified_crawler": false,
    "is_mobile": false,
    "confidence": "high",
    "traits": ["public_dns_resolver", "anycast_network", "internet_infrastructure"],
    "threat_level": "Low"
  },
  "evidence": {
    "signals": [
      {
        "category": "network",
        "label": "Public DNS Resolver",
        "severity": "info",
        "confidence": "high",
        "description": "This IP is a well-known public DNS resolver endpoint."
      }
    ]
  }
}

Root Fields

Field	Type	Description
ip	string	Queried IP address
stack	string	ipv4, ipv6, or unknown
location	object	Approximate geolocation
network	object	ASN, organization, network category, and public operator
routing	object or null	Optional route-origin confidence for the matched prefix
rdap	object	Pro-only normalized RDAP registration contacts, omitted unless include=rdap_contacts is accepted
score	object	Score, band, verdict, and recommended action
classification	object	Proxy, crawler, privacy, datacenter, and threat flags
evidence	object	Structured public signals
decision	object (optional)	Decision Engine v1 recommendation (additive; does not change score)
scores	object (optional)	Decision Engine v1 component sub-scores (0-100 each)
scenarios	object (optional)	Decision Engine v1 per-scenario recommendations
explanation	object (optional)	Decision Engine v1 human-readable explanation and drivers

Field Projection

GET /v1/ip/current and GET /v1/ip/{ip} support fields for top-level response projection:

curl -s "https://api.ipbot.com/v1/ip/8.8.8.8?fields=ip,network,score" | jq

fields accepts ip, stack, location, network, routing, score, classification, evidence, decision, scores, scenarios, and explanation. The returned object contains only the requested top-level fields and preserves each field’s canonical nested structure. Empty fields= or unknown names return 400 INVALID_FIELDS with allowed_fields and invalid_fields in details.

When a Pro API key requests include=rdap_contacts, rdap becomes an additional top-level field and can be projected with fields=rdap. Without the include, fields=rdap is invalid because the public canonical response does not contain RDAP contacts.

Network Object

Field	Type	Description
asn	string	Autonomous System Number
org	string	Organization name associated with the ASN
category	string	Normalized category such as residential, datacenter, cloud, edge, internet_infrastructure, content, network, or unknown
operator	string	Public network operator name when available
operator_type	string	Operator class such as isp, cloud, cdn, content, network_service_provider, mobile_carrier, or enterprise
service_role	string	Stable role for known public infrastructure endpoints, such as public_dns_resolver
service_name	string	User-facing service name, such as Google Public DNS, Cloudflare 1.1.1.1, Telegram, or Stripe Webhooks
routability	string	Public routability class: global, private, non_global, reserved, or bogon
owner	string	Registry owner name when available
allocation	object or null	Allocation CIDR/range/country context when available
radar	object or null	Optional public ASN context without internal cache/source metadata

Pro RDAP Object

rdap is omitted from Free and anonymous responses. It is only returned by GET /v1/ip/current and GET /v1/ip/{ip} when a Pro API key explicitly sends include=rdap_contacts.

Field	Type	Description
available	boolean	Whether normalized RDAP registration data was available for the lookup
cache_status	string	Optional ownership cache state such as fresh or stale
conformance	array	RDAP conformance labels from the RDAP response
network	object or null	Registered network metadata, allocation, events, and RDAP links
contacts	array	RDAP entity contacts with roles, names, organizations, emails, phones, addresses, events, and links
notices	array	RDAP notices from the registry response
remarks	array	RDAP remarks from the registry response
redacted	array	RDAP redaction metadata when the registry reports redacted fields

IPBot still does not expose raw RDAP JSON or raw WHOIS text. The Pro object is normalized, cacheable ownership data extracted from RDAP fields.

Routing Object

Field	Type	Description
origin_asn	string	Origin ASN used for route-origin validation
prefix	string	Matched prefix used for validation
rpki_status	string	valid, invalid_asn, invalid_length, or unknown
confidence	string	low, medium, or high
origin_conflict	boolean	True when optional BGP origin evidence disagrees with lookup or range ASN evidence

Score Object

Field	Type	Description
ip_score	integer	0-100, higher is better
risk_score	integer	0-100, higher is riskier
band	string	perfect, excellent, good, fair, poor, or danger
verdict	string	allow, monitor, challenge, or block
recommended_action	string	allow, rate_limit, captcha_challenge, manual_review, or block

Classification Object

Field	Type	Description
usage_type	string	Product-level usage type such as datacenter, vpn, residential_proxy, or unknown
is_datacenter	boolean	True when hosting/cloud/infrastructure evidence is present
is_proxy	boolean	True when proxy, VPN, Tor, or related proxy evidence is present
is_vpn	boolean	True when VPN evidence is present
is_tor	boolean	True when Tor evidence is present
is_known_abuser	boolean	True when abuse evidence is present
is_residential_proxy	boolean	Present only when residential proxy evidence is known
service_role	string	Stable role for known public infrastructure endpoints
service_name	string	User-facing service name for known public infrastructure endpoints and official service ranges
is_public_resolver	boolean	True for well-known public DNS resolver endpoints
is_anycast	boolean	True when the endpoint is known to be anycasted
is_privacy_relay	boolean	True for privacy relay networks
is_known_crawler	boolean	True when official crawler range evidence is present; known crawlers are not penalized only for a bot-like user agent
is_verified_crawler	boolean	Present and true only when crawler DNS verification passes, or when supported crawler range and user-agent evidence agree
crawler_verified_by	string	Present only for verified crawler evidence, for example reverse_forward_dns or user_agent_ip_range
is_special_use	boolean	True when the IP is in a special-use or non-global address range
special_use_type	string	Stable label such as private, shared_address_space, loopback, documentation, reserved, or unallocated
is_bogon	boolean	True when the IP is not expected as a normal public Internet source address, including dynamic full-bogon evidence when available
is_mobile	boolean	True when the network is classified as a mobile carrier network
proxy_type	string	Normalized proxy type such as vpn, tor, web_proxy, or residential_proxy
confidence	string	low, medium, or high
traits	string[]	Stable traits such as datacenter, cloud_network, known_crawler, public_dns_resolver, anycast_network, proxy, or verified_crawler
threat_level	string	Human-readable threat level

Evidence Object

evidence.signals is the public explanation layer. It is designed for product UI and customer automation.

{
  "signals": [
    {
      "category": "privacy",
      "label": "VPN",
      "severity": "medium",
      "confidence": "medium",
      "description": "This IP is associated with VPN traffic."
    }
  ]
}

Field	Type	Description
category	string	network, privacy, threat, or automation
label	string	User-facing signal label
severity	string	info, low, medium, or high
confidence	string	low, medium, or high
description	string	Short explanation suitable for UI

Data Status Object

GET /v1/data/status returns public service capability readiness. Detailed source versions and coverage counters are reserved for internal operations.

{
  "service_status": "ok",
  "capabilities": [
    "geolocation",
    "asn_intelligence",
    "threat_intelligence",
    "proxy_detection",
    "provider_intelligence",
    "range_intelligence",
    "routability_intelligence",
    "ownership_intelligence",
    "routing_intelligence",
    "service_intelligence",
    "bgp_origin_intelligence",
    "crawler_verification"
  ],
  "coverage_summary": {
    "lookup_ready": true,
    "threat_intelligence_ready": true,
    "proxy_detection_ready": true,
    "provider_intelligence_ready": true,
    "range_intelligence_ready": true,
    "routability_ready": true,
    "ownership_ready": true,
    "routing_ready": true,
    "service_intelligence_ready": true,
    "bgp_origin_ready": false,
    "crawler_verification_ready": true
  }
}

TypeScript Interface

interface IPBotResponse {
  ip: string;
  stack: "ipv4" | "ipv6" | "unknown";
  location: {
    country: string;
    country_code: string;
    region?: string;
    city: string;
    postal?: string;
    latitude: number;
    longitude: number;
    timezone: string;
  };
  network: {
    asn: string;
    org: string;
    category: string;
    operator?: string;
    operator_type?: string;
    service_role?: string;
    service_name?: string;
    routability?: "global" | "private" | "non_global" | "reserved" | "bogon";
    owner?: string;
    allocation?: {
      cidr?: string;
      range?: string;
      registry?: string;
      country?: string;
    };
    radar?: unknown;
  };
  routing?: {
    origin_asn?: string;
    prefix?: string;
    rpki_status?: "valid" | "invalid_asn" | "invalid_length" | "unknown";
    confidence?: "low" | "medium" | "high";
    origin_conflict?: boolean;
  };
  score: {
    ip_score: number;
    risk_score: number;
    band: "perfect" | "excellent" | "good" | "fair" | "poor" | "danger";
    verdict: "allow" | "monitor" | "challenge" | "block";
    recommended_action: "allow" | "rate_limit" | "captcha_challenge" | "manual_review" | "block";
  };
  classification: {
    usage_type: string;
    is_datacenter: boolean;
    is_proxy: boolean;
    is_cloud?: boolean;
    cloud_provider?: string;
    service_role?: string;
    service_name?: string;
    is_public_resolver?: boolean;
    is_anycast?: boolean;
    is_edge_network?: boolean;
    is_privacy_relay?: boolean;
    privacy_relay_provider?: string;
    is_known_crawler?: boolean;
    is_verified_crawler?: boolean;
    crawler_provider?: string;
    is_special_use?: boolean;
    special_use_type?: string;
    is_bogon?: boolean;
    is_mobile?: boolean;
    proxy_type?: string;
    confidence: "low" | "medium" | "high";
    traits?: string[];
    is_vpn?: boolean;
    is_tor?: boolean;
    is_known_abuser?: boolean;
    is_residential_proxy?: boolean;
    threat_level: string;
  };
  evidence: {
    signals: Array<{
      category: string;
      label: string;
      severity: "info" | "low" | "medium" | "high";
      confidence: "low" | "medium" | "high";
      description: string;
    }>;
  };
  // Decision Engine v1 — additive, optional. Does not change score/verdict/recommended_action.
  decision?: {
    profile: string;
    role: string;
    action: "allow" | "monitor" | "challenge" | "rate_limit" | "manual_review" | "block";
    risk_level: "low" | "medium" | "high";
    confidence: "low" | "medium" | "high";
    policy_version: string;
    allowed_actions: string[];
    blocked_actions: string[] | null;
    guardrails_applied: string[] | null;
  };
  scores?: {
    risk_score: number;
    base_risk_score: number;
    abuse_score: number;
    anonymity_score: number;
    trust_score: number;
    infrastructure_score: number;
    routing_risk_score: number;
    evidence_quality_score: number;
  };
  scenarios?: Record<
    "content" | "seo_crawler" | "login" | "signup" | "payment" | "api",
    {
      action: string;
      risk_level: string;
      confidence: string;
      reason: string;
    }
  >;
  explanation?: {
    summary: string;
    key_reason: string;
    drivers: Array<{
      type: string;
      label: string;
      impact: string;
      impact_score: number;
      direction: "raises_risk" | "lowers_risk";
      reason: string;
    }>;
    guardrails_applied: string[];
    reason_chain: string[];
  };
}

Decision Engine

The Decision Engine adds four optional, additive top-level objects to the v1 lookup response: decision, scores, scenarios, and explanation. They are purely advisory and do not change score.risk_score, score.verdict, or score.recommended_action. Clients that do not consume these fields keep working unchanged. Any of these objects may be absent.

{
  "decision": {
    "profile": "balanced",
    "role": "datacenter",
    "action": "monitor",
    "risk_level": "medium",
    "confidence": "high",
    "policy_version": "decision-v1-2026-06.2",
    "allowed_actions": ["allow", "monitor", "challenge"],
    "blocked_actions": null,
    "guardrails_applied": ["verified_crawler_protection"]
  },
  "scores": {
    "risk_score": 30,
    "base_risk_score": 28,
    "abuse_score": 0,
    "anonymity_score": 10,
    "trust_score": 90,
    "infrastructure_score": 80,
    "routing_risk_score": 0,
    "evidence_quality_score": 85
  },
  "scenarios": {
    "content": { "action": "allow", "risk_level": "low", "confidence": "high", "reason": "Trusted infrastructure" },
    "seo_crawler": { "action": "allow", "risk_level": "low", "confidence": "high", "reason": "Known good network" },
    "login": { "action": "monitor", "risk_level": "medium", "confidence": "medium", "reason": "Datacenter origin" },
    "signup": { "action": "challenge", "risk_level": "medium", "confidence": "medium", "reason": "Datacenter origin" },
    "payment": { "action": "challenge", "risk_level": "high", "confidence": "medium", "reason": "Elevated payment risk" },
    "api": { "action": "monitor", "risk_level": "low", "confidence": "high", "reason": "Automation expected" }
  },
  "explanation": {
    "summary": "Datacenter network with strong infrastructure trust and no abuse history.",
    "key_reason": "datacenter_origin",
    "drivers": [
      {
        "type": "infrastructure",
        "label": "Datacenter Origin",
        "impact": "+10",
        "impact_score": 10,
        "direction": "raises_risk",
        "reason": "Traffic originates from a hosting/datacenter network."
      }
    ],
    "guardrails_applied": ["verified_crawler_protection"],
    "reason_chain": ["base_risk=28", "datacenter_origin", "policy=balanced"]
  }
}

decision Object

Field	Type	Description
profile	string	Policy profile that produced this decision
role	string	Inferred role of the IP (for example datacenter, residential, crawler)
action	string	Recommended action: allow, monitor, challenge, rate_limit, manual_review, or block
risk_level	string	low, medium, or high
confidence	string	low, medium, or high
policy_version	string	Version of the decision policy applied
allowed_actions	string[]	Actions permitted under the active policy
blocked_actions	string[] or null	Actions explicitly blocked, or null when none
guardrails_applied	string[] or null	Guardrails that constrained the decision, or null when none

scores Object

Eight component sub-scores, each 0-100. These break down how the assessment is composed and are advisory only.

Field	Type	Description
risk_score	integer	Composite risk (0-100)
base_risk_score	integer	Base risk before policy adjustments
abuse_score	integer	Known-abuse contribution
anonymity_score	integer	Proxy/VPN/Tor anonymity contribution
trust_score	integer	Positive trust contribution (higher = more trusted)
infrastructure_score	integer	Infrastructure/datacenter contribution
routing_risk_score	integer	Route-origin/RPKI risk contribution
evidence_quality_score	integer	Confidence in the supporting evidence

scenarios Object

Per-scenario recommendation keyed by scenario name (content, seo_crawler, login, signup, payment, api). Each value has the same shape. In v1, scenario confidence reuses the top-level decision.confidence value.

Field	Type	Description
action	string	Recommended action for this scenario
risk_level	string	low, medium, or high for this scenario
confidence	string	low, medium, or high
reason	string	Short explanation for the scenario recommendation

explanation Object

Field	Type	Description
summary	string	Human-readable summary of the decision
key_reason	string	Primary driver identifier
drivers	array	Individual factors influencing risk
drivers[].type	string	Driver category
drivers[].label	string	User-facing driver label
drivers[].impact	string	Signed impact magnitude (for example +10)
drivers[].impact_score	integer	Numeric impact contribution
drivers[].direction	string	raises_risk or lowers_risk
drivers[].reason	string	Short explanation for the driver
guardrails_applied	string[]	Guardrails that constrained the decision
reason_chain	string[]	Ordered reasoning steps