IPBot
Get Started
API Reference

Build with the IPBot API

Everything you need to call the API: endpoints, parameters, 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 /8.8.8.8 
{
  "ip": "203.0.113.1",
  "location": {
    "country": "United States",
    "region": "California",
    "city": "San Francisco",
    "timezone": "-08:00"
  },
  "network": {
    "asn": "AS15169",
    "org": "Example ISP Inc."
  },
  "security": {
    "risk_score": 10,
    "is_proxy": false,
    "threat_level": "Low"
  }
}
GET /

Auto-detect the caller IP using trusted proxy headers.

curl -s https://api.ipbot.com/ | jq
GET /{ip}

Lookup a specific IPv4 or IPv6 address.

curl -s https://api.ipbot.com/8.8.8.8 | jq
GET /api?ip={ip}

Lookup via query param when path segments are not convenient.

curl -s "https://api.ipbot.com/api?ip=8.8.8.8" | 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. 

X-API-Key: ipb_free_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Endpoints

Method Path Description
GET / Auto-detect the caller IP using trusted proxy headers.
GET /{ip} Lookup a specific IPv4 or IPv6 address.
GET /api?ip={ip} Lookup via query param when path segments are not convenient.
GET /asn/{asn} Lookup ASN details with enriched insights.
GET /health Health check endpoint for liveness and readiness.
POST /reload Admin-only: reloads rules, threat lists, and IP2Location data.
GET /auth/github Initiates GitHub OAuth flow for authentication.
GET /auth/me Returns current authenticated user profile.
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.

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_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.
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.