API Documentation

🔐 Authentication & Base URL

All API calls are made against the public API hostname:

https://api.ipintel.ai

Authentication is done via an api_key query parameter:

?api_key=YOUR_API_KEY

You can create and manage API keys from your IPIntel.ai dashboard. Each key is bound to a plan (Ghost, Sentinel, Oracle, Overseer), and inherits its rate limits and endpoint access.

Every successful response also includes:

• api_plan – the name of the active plan for this key
• api_usage – current usage vs. quota: sec_limit, min_limit, day_limit
• response_ms – time to generate the response on the backend

📦 Endpoint Access by Plan

All plans include full IP-level threat scoring. Higher-tier plans unlock network-level context:

If your plan does not include a given endpoint, the API returns a structured 403 JSON error with allowed_plans and an upgrade hint.

🔍 IP Lookup

Returns full threat intelligence for a single IP: final score, confidence, behavior badges, bot detection, and geo/network context.

• Path param: {ip} – required, IPv4 or IPv6 address
• Query: api_key – required, your API key

Sample response:

{
    "ip": "20.204.24.249",
    "country": "India",
    "country_code": "IN",
    "region": "Maharashtra",
    "region_code": "MH",
    "city": "Pune",
    "isp": "Microsoft Corporation",
    "org": "Microsoft Azure Cloud (centralindia)",
    "asn": "AS8075",
    "as_name": "Microsoft Corporation",
    "latitude": "18.5144",
    "longitude": "73.864235",
    "timezone": "Asia\/Kolkata",
    "reverse_dns": "",
    "is_tor_exit": false,
    "risk_score": 16,
    "threat_score": 22,
    "confidence_level": 100,
    "risk_summary": "This IP exhibits low-level activity that is occasionally associated with automated or non-human access. This assessment is supported by strong and consistent detection signals. When threat severity and confidence are combined, the overall risk posed by this IP is considered negligible. No defensive action is required at this time.",
    "summary": "The IP exhibits suspicious behavior with a malformed user-agent indicating potential automation. It originates from a known cloud provider and lacks JavaScript support, suggesting possible evasion tactics. The access pattern is limited but concerning due to the nature of the user-agent.",
    "ai_supernet_summary": "The subnet exhibits coordinated behavior with repetitive, low-interaction visits to a specific domain using a common user agent associated with a bot. The lack of forward DNS matches and the consistent use of the same user agent across multiple IPs suggest potential automation and scraping activities, raising concerns about analytics pollution.",
    "status": "safe",
    "badges": [
        {
            "flag": "spider",
            "label": "Spider",
            "emoji": "🕷️"
        }
    ],
    "javascript_support": false,
    "user_agents": [
        "Mozilla\/5.0 AppleWebKit\/537.36 (KHTML, like Gecko); compatible; ChatGPT-User\/1.0; +https:\/\/openai.com\/bot"
    ],
    "verified_bot": true,
    "verified_bot_name": "ChatGPT-User",
    "verified_bot_type": "AI bot",
    "api_plan": "Ghost",
    "api_usage": {
        "sec_limit": "1\/2",
        "min_limit": "1\/60",
        "day_limit": "8\/500"
    },
    "response_ms": 2.9
}

🛰️ Subnet Lookup

Returns aggregated threat signal for a /24 (IPv4) or /48 (IPv6) subnet: subnet score, seen IPs, and ASNs.

• Path param: {subnet} – required, e.g. 140.235.170.0/24
• Query: api_key – required, your API key

Sample response:

{
  "subnet": "140.235.170.0/24",
  "subnet_score": 81,
  "top_badges": [],
  "ips_seen": 1,
  "ips": [
    "140.235.170.215"
  ],
  "asns": [
    "AS26548"
  ],

  "api_plan": "Oracle",
  "api_usage": {
    "sec_limit": "1/20",
    "min_limit": "4/300",
    "day_limit": "281/50000"
  },

  "response_ms": 5.4
}

🗺️ Supernet Lookup

Analyzes an entire /16 (IPv4) or /32 (IPv6) supernet to uncover coordinated, low-frequency attackers that rotate IPs across the same network.

• Path param: {supernet} – required, e.g. 140.235.0.0/16 or 2a02:6b8::/32
• Query: api_key – required, your API key

Sample response:

{
  "supernet": "140.235.0.0/16",
  "subnets_seen": 2,
  "supernet_score": 76,
  "top_badges": [],

  "ai_score": 0,
  "ai_summary": "",
  "ai_tags": [],

  "country_counts": { "us": 2 },
  "country_names": { "us": "United States" },

  "subnet_counts": {
    "169": 1,
    "170": 1
  },
  "active_subnets": [
    "140.235.0.0.169.0/24",
    "140.235.0.0.170.0/24"
  ],

  "marker_coords": [
    { "lat": 46.89, "lng": -114.046, "level": 71 }
  ],

  "asns": [
    "AS26548"
  ],

  "api_plan": "Oracle",
  "api_usage": {
    "sec_limit": "1/20",
    "min_limit": "1/300",
    "day_limit": "278/50000"
  },

  "response_ms": 18.7
}

🏢 ASN Lookup

Returns threat reputation for an entire ASN: number of IPs seen, ASN score, and behavioral badges. Useful to treat entire hosting providers or networks as risky zones.

• Path param: {asn} – required, either AS26548 or 26548
• Query: api_key – required, your API key

Sample response (truncated ips list):

{
  "asn": "AS26548",
  "as_name": "PureVoltage Hosting Inc.",
  "ips_seen": 700,
  "asn_score": 73,
  "top_badges": [
    "server_errors",
    "honeypot_hit"
  ],
  "ips": [
    "5.181.170.189",
    "23.230.223.241",
    "45.10.166.17",
    "45.10.166.21",
    "..."
  ],

  "api_plan": "Overseer",
  "api_usage": {
    "sec_limit": "1/20",
    "min_limit": "1/300",
    "day_limit": "283/50000"
  },

  "response_ms": 62.3
}

📊 Rate Limits & Usage

Rate limits are defined per plan in your account and enforced globally per API key. Each response includes your current usage snapshot:

"api_usage": {
  "sec_limit": "1/20",
  "min_limit": "1/300",
  "day_limit": "274/50000"
}

• sec_limit – used/allowed calls in the current second
• min_limit – used/allowed calls in the current minute
• day_limit – used/allowed calls in the current UTC day

Plan Limits

Daily quotas reset at 00:00 UTC. Per-second and per-minute buckets are enforced continuously.

🚨 Error Handling

On error, the API returns an appropriate HTTP status code and a JSON object with an error message.

• 400 – bad request (missing or invalid parameter)
• 401 – missing API key
• 403 – invalid / revoked key, or plan not allowed for this endpoint
• 404 – no data for the requested resource
• 429 – rate limit or daily quota exceeded
• 500 – internal server error

Example: invalid or downgraded plan for endpoint

{
  "error": "Your plan (Oracle) does not include access to 'asn'.",
  "allowed_plans": [
    "Overseer"
  ],
  "upgrade_hint": "Upgrade your plan to access this endpoint."
}

Example: missing API key

{
  "error": "Missing API key"
}

✅ Best Practices

• Use persistent HTTP clients and connection pooling on your side to minimize latency.
• Cache non-critical lookups in your own layer to avoid hitting rate limits unnecessarily.
• Use threat_score and confidence_level together when making block / allow decisions.
• Combine IP-level data with subnet_score, supernet_score and asn_score for deeper risk models.
• Rotate keys if you suspect compromise; revoked keys are blocked instantly by the API edge.