Build with the IPBot API

Base URL

Canonical /v1 endpoints return JSON and include CORS headers. The two legacy lookup routes also support an explicit plain-text representation for command-line use.

https://api.ipbot.com

Plain text (legacy)

GET / and GET /{ip} return JSON by default. Request text with ?format=text or an Accept: text/plain header. The query parameter takes precedence; otherwise text is selected only when its accepted quality is higher than JSON (or an exact text match is more specific). Canonical /v1 routes remain JSON-only.

curl -s -H "Accept: text/plain" https://api.ipbot.com/

curl -s "https://api.ipbot.com/8.8.8.8?format=text&detail=1"

Authentication

Anonymous access is supported with a baseline rate limit. Use an API key to raise your throughput. Pro-only fields require an authenticated Pro API key.

X-API-Key: ipb_free_REPLACE_ME

V1 Lookup Parameters

GET /v1/ip/current and GET /v1/ip/{ip} support response projection. Legacy routes and /v1/assessment keep their existing response shape.

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

{
  "ip": "8.8.8.8",
  "location": {
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "city": "Mountain View",
    "timezone": "-07:00"
  },
  "score": {
    "ip_score": 85,
    "risk_score": 15,
    "band": "good",
    "verdict": "allow",
    "recommended_action": "allow"
  }
}

curl -s "https://api.ipbot.com/v1/ip/8.8.8.8?include=rdap_contacts&fields=ip,rdap" \
  -H "X-API-Key: $IPBOT_PRO_API_KEY" | jq

{
  "ip": "8.8.8.8",
  "rdap": {
    "available": true,
    "network": {
      "handle": "NET-8-8-8-0-1",
      "name": "GOGL",
      "registry": "arin",
      "registered_owner": "Google LLC",
      "allocation": {
        "cidr": "8.8.8.0/24",
        "range": "8.8.8.0 - 8.8.8.255",
        "registry": "arin",
        "country": "US"
      }
    },
    "contacts": [
      {
        "handle": "GOGL",
        "roles": ["registrant"],
        "name": "Google LLC",
        "organization": "Google LLC",
        "phones": ["+1-555-0100"]
      },
      {
        "roles": ["abuse"],
        "name": "Google Abuse",
        "emails": ["abuse@example.com"]
      }
    ]
  }
}

Without a Pro key, include=rdap_contacts returns 403 PRO_REQUIRED. Unknown include names return 400 INVALID_INCLUDE. Empty or unknown fields return 400 INVALID_FIELDS.

{
  "error": "RDAP contacts require a Pro API key",
  "code": "PRO_REQUIRED",
  "details": {
    "include": "rdap_contacts",
    "allowed_includes": ["rdap_contacts"]
  }
}

{
  "error": "Invalid fields parameter",
  "code": "INVALID_FIELDS",
  "details": {
    "allowed_fields": [
      "ip",
      "stack",
      "location",
      "network",
      "routing",
      "score",
      "classification",
      "evidence",
      "decision",
      "scores",
      "scenarios",
      "explanation"
    ],
    "invalid_fields": ["bogus"]
  }
}

Evidence Fields

IPBot returns product-level IP intelligence: network category, classification confidence, verdict, recommended action, and structured signals. Internal source and version details are not part of the public response contract.

Decision Engine

Decision Engine v1 adds four optional, additive top-level objects to v1 IP lookup responses: decision, scores, scenarios, and explanation. These fields are advisory only and do not change score.risk_score, score.verdict, or score.recommended_action.

scenarios.*.confidence is computed per scenario from that scenario's own expected-loss margin and supporting evidence; it is not a copy of decision.confidence.

curl -s "https://api.ipbot.com/v1/ip/8.8.8.8?fields=decision,scores,scenarios,explanation" | jq

{
  "decision": {
    "profile": "ordinary_datacenter",
    "role": "datacenter",
    "action": "monitor",
    "risk_level": "medium",
    "confidence": "high",
    "policy_version": "decision-v1-2026-07.1",
    "allowed_actions": ["allow", "monitor", "challenge"],
    "blocked_actions": null,
    "guardrails_applied": ["verified_crawler_protection"]
  },
  "scores": {
    "risk_score": 42,
    "base_risk_score": 40,
    "abuse_score": 8,
    "anonymity_score": 12,
    "trust_score": 62,
    "infrastructure_score": 74,
    "routing_risk_score": 4,
    "evidence_quality_score": 86
  },
  "scenarios": {
    "content": { "action": "allow", "risk_level": "low", "confidence": "high", "reason": "Low abuse pressure" },
    "seo_crawler": { "action": "allow", "risk_level": "low", "confidence": "high", "reason": "Known automation expected" },
    "login": { "action": "monitor", "risk_level": "medium", "confidence": "medium", "reason": "Datacenter origin" },
    "signup": { "action": "challenge", "risk_level": "medium", "confidence": "medium", "reason": "Higher fraud surface" },
    "payment": { "action": "manual_review", "risk_level": "high", "confidence": "medium", "reason": "Elevated payment risk" },
    "api": { "action": "monitor", "risk_level": "low", "confidence": "high", "reason": "Automation expected" }
  },
  "explanation": {
    "summary": "Datacenter-origin traffic with moderate anonymity pressure and no strong 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=40", "datacenter_origin", "policy=balanced"]
  }
}

Crawler Verification

POST /v1/crawler/verify is a narrow verification endpoint for site-owner workflows. It accepts an ip and optional user_agent, returns verification_status as verified, known_unverified, or not_known, and always responds with Cache-Control: no-store.

curl -s -X POST https://api.ipbot.com/v1/crawler/verify \
  -H "Content-Type: application/json" \
  -d '{"ip":"66.249.66.1","user_agent":"Googlebot/2.1 (+http://www.google.com/bot.html)"}' | jq

{
  "ip": "66.249.66.1",
  "user_agent": "Googlebot/2.1 (+http://www.google.com/bot.html)",
  "verification_status": "verified",
  "classification": {
    "is_known_crawler": true,
    "is_verified_crawler": true,
    "crawler_provider": "Google",
    "crawler_type": "googlebot",
    "crawler_verified_by": "reverse_forward_dns",
    "crawler_hostname": "crawl-66-249-66-1.googlebot.com."
  },
  "network": {
    "owner": "Google LLC",
    "allocation": {
      "cidr": "66.249.64.0/19",
      "registry": "arin",
      "country": "US"
    }
  },
  "explanation": {
    "text": "Google googlebot is verified by reverse and forward DNS, and the hostname resolves back to this IP.",
    "reason_code": "verified_crawler"
  }
}

Endpoints

ASN Response

/v1/asn/{asn} is the canonical ASN route. It always returns 200 for a valid ASN, even when Cloudflare Radar is unavailable, by falling back to IPBot's local ASN name and any evidence-only context it can still derive. The legacy /asn/{asn} route remains as a compatibility alias.

radar is optional enrichment. threat_density and asndrop are evidence-only ASN context and do not change per-IP risk_score.

{
  "asn": "AS64500",
  "name": "Example Network",
  "radar": null,
  "threat_density": {
    "threat_network_count": 2,
    "threat_ipv4_addresses": 512,
    "total_ipv4_addresses": 1048576,
    "ratio": 0.00048828125,
    "percent": 0.048828125,
    "significant": false,
    "source": "threat_lists+iptoasn"
  },
  "asndrop": {
    "asn": "AS64500",
    "as_name": "EXAMPLE-NETWORK",
    "rir": "arin",
    "domain": "example.net",
    "country_code": "US"
  }
}

Error Responses

All errors follow a consistent JSON format.

{
  "error": "Invalid IP address format",
  "code": "INVALID_IP",
  "details": {
    "provided": "invalid-ip"
  }
}