IPBot
Get Started
API Reference

Build with the IPBot API

Everything you need to call the API: endpoints, evidence fields, data status, and error codes. Anonymous access works out of the box, and free API keys unlock higher limits.

Quickstart Browse Docs
CORS enabled JSON responses API key optional
Example response GET /v1/ip/8.8.8.8 
{
  "ip": "203.0.113.1",
  "stack": "ipv4",
  "location": {
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "city": "San Francisco",
    "timezone": "-08:00"
  },
  "network": {
    "asn": "AS15169",
    "org": "Example ISP Inc.",
    "category": "residential",
    "operator": "Example ISP",
    "operator_type": "isp",
    "owner": "Example ISP Inc.",
    "allocation": {
      "cidr": "203.0.113.0/24",
      "range": "203.0.113.0 - 203.0.113.255",
      "registry": "arin",
      "country": "US"
    }
  },
  "routing": {
    "origin_asn": "AS15169",
    "prefix": "203.0.113.0/24",
    "rpki_status": "unknown",
    "confidence": "low",
    "origin_conflict": false
  },
  "score": {
    "ip_score": 60,
    "risk_score": 40,
    "band": "fair",
    "verdict": "monitor",
    "recommended_action": "rate_limit"
  },
  "classification": {
    "usage_type": "vpn",
    "is_datacenter": false,
    "is_proxy": true,
    "is_privacy_relay": false,
    "is_known_crawler": false,
    "is_verified_crawler": false,
    "is_mobile": false,
    "proxy_type": "vpn",
    "confidence": "medium",
    "traits": ["proxy", "vpn"],
    "threat_level": "Low"
  },
  "evidence": {
    "signals": [
      {
        "category": "privacy",
        "label": "VPN",
        "severity": "medium",
        "confidence": "medium",
        "description": "This IP is associated with VPN traffic."
      }
    ]
  }
}
GET /v1/ip/current

Auto-detect the caller IP with v1 schema. Supports fields projection and Pro RDAP include.

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

Lookup a specific IPv4 or IPv6 address with v1 schema. Supports fields projection and Pro RDAP include.

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

Dual-stack assessment; supports ?ipv4= and ?ipv6=.

curl -s "https://api.ipbot.com/v1/assessment?ipv4=8.8.8.8&ipv6=2001:4860:4860::8888" | jq

Base URL

All endpoints return JSON and include CORS headers.

https://api.ipbot.com

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.

Parameter Required Description
fields No Comma-separated top-level response fields: ip, stack, location, network, routing, score, classification, evidence. With Pro RDAP enabled, rdap can also be projected.
include No Optional include list. include=rdap_contacts is Pro-only and adds normalized RDAP registration/contact data.

Field Projection

fields trims the canonical v1 response. It does not create a new schema or rename nested fields. 

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

Pro RDAP Contacts

Free and anonymous responses never expose RDAP contact emails, phones, addresses, person records, raw RDAP JSON, or raw WHOIS text. Pro keys can request the normalized object explicitly. After the include is accepted, use fields=rdap to return only the RDAP object. 

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"]
  }
}

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.

Proxy and privacy signals

proxy_type, is_proxy, is_vpn, is_tor, and is_privacy_relay describe public classifications without exposing the underlying data vendor.

Structured evidence

evidence.signals contains stable labels, categories, severities, confidence, and short explanations suitable for product UI.

Crawler protection

is_known_crawler comes from official ranges, including supported search crawler feeds, and avoids generic bot-UA over-scoring. is_verified_crawler, crawler_verified_by, and crawler_hostname are present only after DNS verification or supported range + user-agent verification succeeds.

Routability checks

network.routability, is_special_use, and is_bogon explain private, reserved, documentation, dynamic full-bogon, and other non-global address states without exposing raw source names.

Operator and service context

network.category, operator_type, and service_name may include provider-declared content, network service provider, webhook, messaging, or crawler infrastructure context.

Data status

/v1/data/status reports public service and capability readiness. Detailed source readiness is reserved for internal operations.

RDAP boundary

network.owner and network.allocation come from normalized RDAP ownership data when available. Full RDAP contacts only appear in Pro responses after include=rdap_contacts.

Endpoints

Method Path Description
GET /v1/ip/current Auto-detect the caller IP with v1 schema. Supports fields projection and Pro RDAP include.
GET /v1/ip/{ip} Lookup a specific IPv4 or IPv6 address with v1 schema. Supports fields projection and Pro RDAP include.
GET /v1/assessment Dual-stack assessment; supports ?ipv4= and ?ipv6=.
GET /v1/data/status Public service status and high-level intelligence capabilities.
GET / Legacy auto-detect endpoint (compatible).
GET /{ip} Legacy lookup endpoint (compatible).
GET /asn/{asn} Lookup ASN details with enriched insights.
GET /health Health check endpoint for liveness and readiness.
GET /metrics Operator-only Prometheus metrics for HTTP traffic and operational coverage counters.
POST /reload Admin-only: reloads runtime rules and intelligence data.
GET /auth/github Initiates GitHub OAuth flow for authentication.
GET /auth/me Returns current authenticated user profile.
GET /auth/tiers Returns tier limits and current tier context.
POST /auth/logout Clears the session and logs out the user.
GET /auth/keys Lists all API keys for the authenticated user.
POST /auth/keys Creates a new API key.
DELETE /auth/keys/{id} Revokes an API key immediately.
GET /auth/usage Returns request usage summary by API key.

Error Responses

All errors follow a consistent JSON format.

{
  "error": "Invalid IP address format",
  "code": "INVALID_IP",
  "details": {
    "provided": "invalid-ip"
  }
}
Code HTTP Description
INVALID_IP 400 Malformed or invalid IP address.
INVALID_FIELDS 400 The fields projection is empty or contains unknown fields.
INVALID_INCLUDE 400 The include parameter contains an unsupported include name.
INVALID_ASN 400 Malformed or invalid ASN format.
NO_CLIENT_IP 400 Unable to determine client IP.
UNAUTHORIZED 401 Authentication required.
INVALID_API_KEY 401 The API key is invalid or revoked.
FORBIDDEN 403 Access denied for admin routes.
PRO_REQUIRED 403 The requested include, such as rdap_contacts, requires a Pro API key.
NOT_FOUND 404 Endpoint or resource does not exist.
RATE_LIMITED 429 Rate limit exceeded.
INTERNAL_ERROR 500 Unexpected server error.
AUTH_DISABLED 503 Authentication not configured.