API reference

Agentscan API

AI-agent and bot detection.

Base URLhttps://ipscanner.io

Authenticate every request with Authorization: Bearer YOUR_API_KEY. Create a key in your account.

Edge snippet (agentscan.js)

A tiny browser script that collects client-side automation tells (webdriver, headless User-Agent, GPU, plugins, languages) and beacons them to your backend. Your backend then forwards them, plus the request IP and JA4 it sees server-side, to POST /v1/agentscan/check. The browser cannot read the real client IP or TLS fingerprint, so the verdict is finished server-side.

Install

<!-- Auto-beacon: collects on load and POSTs to your endpoint -->
<script src="https://ipscanner.io/agentscan.js"
        data-endpoint="/your/collect" defer></script>

Usage

// Programmatic API exposed on window.Agentscan

// 1. Read the collected client signals
const signals = window.Agentscan.collect();
// -> { headless_flags: { webdriver, headless_ua, ... }, user_agent, client: {...} }

// 2. Or send them to your backend (uses navigator.sendBeacon, falls back to fetch)
await window.Agentscan.send('/your/collect');

// 3. On your server, add the IP + JA4 you see and call the API:
//    POST https://ipscanner.io/v1/agentscan/check
//    { ip, ja4, ...signals }

Serve the script from ipscanner.io/agentscan.js, or self-host a copy. It has no dependencies and adds the global window.Agentscan { collect, send }.

POSTClassify a request GETList the allowlist

POST/v1/agentscan/check

Classify a request

Returns one of human, known_bot, ai_agent or malicious_automation for a request, with a confidence and a recommended action. Send the signals collected by the edge snippet; the API adds the IP origin and verifies the allowlist.

Parameter	In	Type	Required	Description
ip	body	string	required	The client IP as seen at your edge.
user_agent	body	string	optional	The request User-Agent header.
ja4	body	string	optional	JA4 TLS client fingerprint, if your edge captures it.
headless_flags	body	object	optional	Client-JS automation tells from the snippet, e.g. { "webdriver": true }.
headers	body	object	optional	Selected request headers for the consistency check.
request_id	body	string	optional	Optional id echoed into the rolling signal log.

Request body

{
  "ip": "198.51.100.7",
  "user_agent": "Mozilla/5.0 HeadlessChrome/120",
  "ja4": "t13d1516h2_8daaf6152771_...",
  "headless_flags": {
    "webdriver": true
  },
  "headers": {
    "Accept": "*/*"
  }
}

Response

{
  "class": "malicious_automation",
  "confidence": 0.9,
  "action": "block",
  "signals": {
    "network_origin": "datacenter",
    "anonymized": true,
    "headless": true,
    "allowlist_verified": false
  }
}

POST /v1/agentscan/check

curl -X POST 'https://ipscanner.io/v1/agentscan/check' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"ip":"198.51.100.7","user_agent":"Mozilla/5.0 HeadlessChrome/120","ja4":"t13d1516h2_8daaf6152771_...","headless_flags":{"webdriver":true},"headers":{"Accept":"*/*"}}'

GET/v1/agentscan/allowlist

List the allowlist

Returns the verified good-bot allowlist in effect for your account: the global entries (Googlebot, Bingbot, GPTBot and more) plus any you have added. customer_id is null for global entries.

Response

{
  "agents": [
    { "id": 1, "ident": "googlebot", "type": "search", "verification_method": "reverse_dns:googlebot.com,google.com", "customer_id": null },
    { "id": 42, "ident": "partnerbot", "type": "partner", "verification_method": "ua_match", "customer_id": 17 }
  ]
}

GET /v1/agentscan/allowlist

curl -X GET 'https://ipscanner.io/v1/agentscan/allowlist' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'