API documentation

Base URL https://detectip.ai · authenticate with X-API-Key: sk_live_...

IP geolocation lookup

For a quick, browser-side geolocation of the current visitor (IP, country, city, currency and a threat flag), call the public widget endpoint — no key required, rate-limited:

GET https://detectip.ai/v1/myip

{
  "ip": "203.0.113.7", "country": "DE", "country_name": "Germany",
  "city": "Berlin", "currency": "EUR", "currency_symbol": "\u20ac",
  "threat": false
}

ISP, ASN, exact proxy/VPN/Tor and 100+ fields require an API key via /api/v1/verdict (full geolocation + threat verdict). See the Geolocation API overview.

How it works

detectip.ai fingerprints a visitor's browser/connection across the network, behavioral and IP layers, then returns an explainable bot-vs-human verdict.

Add the collector tag to your page with your public key. It fingerprints the visitor and ties them to a session token (cookie botd_token).
From your backend, call /api/v1/verdict with that token and your secret key.

1. Add the collector

<script src="https://detectip.ai/collector.js" data-key="pk_live_..."></script>

2. Get a verdict

GET /api/v1/verdict?token=SESSION_TOKEN

Response

{
  "token": "…",
  "score": 96,            // 0 (human) … 100 (bot)
  "band": "known-bot",    // human | suspicious | automated | known-bot
  "hard_rule_hit": "",    // set when a definitive rule fired
  "signals": [            // explainable contributions (log-likelihood ratios)
    { "name": "non_browser_tls_stack", "layer": "tls", "llr": 1.7,
      "detail": "TLS stack is not a known browser" },
    { "name": "ip_datacenter", "layer": "ip", "llr": 1.86,
      "detail": "datacenter ASN" }
  ],
  "network": { "ja4": "t13d…" },
  "ip": { "datacenter": true, "proxy": false, "country": "AE" }
}

Fields beyond score/band/JA4/IP flags (deep fingerprints, reputation, per-signal detail) are included according to your plan.

Active protection (enforcement)

Every verdict includes a recommended action: allow, challenge or block (derived from the score thresholds; a hard rule always blocks). Enforce it in your backend:

const v = await (await fetch(
  "https://detectip.ai/api/v1/verdict?token=" + token,
  { headers: { "X-API-Key": process.env.DETECTIP_KEY } }
)).json();

switch (v.action) {
  case "block":     return res.status(403).end();   // hard bot
  case "challenge": return showInterstitial();       // PoW / captcha
  default:          return next();                    // allow
}

For simple sites with no backend, add data-enforce to the tag and the script will challenge or block automatically:

<script src="https://detectip.ai/collector.js" data-key="pk_live_..." data-enforce></script>

The script also fires a botd:verdict DOM event so you can implement custom handling instead.

Usage

GET /api/v1/usage → { "tier", "used", "limit", "remaining" }

Errors

Status	Meaning
401	Missing / invalid / revoked API key
402	Monthly quota exceeded — upgrade
404	No captured session for token
429	Rate limit exceeded

OpenAPI spec · Get your API key