NORAD API DOCUMENTATION

Free REST API for real-time AI bot detection and monitoring. Track GPTBot, ClaudeBot, PerplexityBot, Bytespider and 30+ AI crawlers across the global web. No authentication required for public endpoints.

BASE URL: https://api.clawbotden.comSTATUS: OPERATIONAL

QUICK START

Get live AI bot detections in one line:

curl https://api.clawbotden.com/api/v1/public/norad/live

Returns the latest 100 bot detection events with geolocation, bot type, risk assessment, and timestamps.

PUBLIC ENDPOINTS

All public endpoints are free, require no API key, and have a rate limit of 60 requests per minute.

GET/api/v1/public/norad/live

Live Bot Events

Get the latest 100 real-time bot detection events. Each event includes bot type, geolocation (country, city, coordinates), risk decision, and timestamp. Perfect for building live dashboards or feeding into your SIEM.

RESPONSE
[
  {
    "id": "a1b2c3d4-e5f6-...",
    "bot_type": "GPTBot",
    "decision": "allow",
    "trust_score": null,
    "country_code": "US",
    "city": "San Francisco",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "created_at": "2026-02-17T21:56:22Z"
  },
  ...
]
GET/api/v1/public/norad/stats

Dashboard Statistics

Aggregated 24-hour statistics: total bots tracked, threats detected, sites protected, system uptime. Use for overview widgets and status pages.

RESPONSE
{
  "sites_protected": 460,
  "bots_tracked_24h": 157,
  "threats_detected": 8,
  "bots_denied_24h": 0,
  "uptime": "99.97%",
  "last_updated": "2026-02-17T21:57:28Z"
}
GET/api/v1/public/norad/bot-types

Bot Type Breakdown

24-hour breakdown by bot type. Shows which AI crawlers are most active: GPTBot, ClaudeBot, Googlebot, YandexBot, Bytespider, etc. Sorted by frequency.

RESPONSE
[
  { "bot_type": "Googlebot", "count": 43 },
  { "bot_type": "YandexBot", "count": 95 },
  { "bot_type": "GPTBot", "count": 3 },
  { "bot_type": "ClaudeBot", "count": 2 },
  ...
]
GET/api/v1/public/norad/feed

Event Feed

Human-readable event feed with formatted messages. Ideal for SIEM integrations, Slack/Discord webhooks, or log aggregation. Includes natural language action descriptions.

RESPONSE
[
  {
    "id": "...",
    "bot_type": "GPTBot",
    "decision": "allow",
    "country_code": "US",
    "city": "New York",
    "trust_score": null,
    "created_at": "2026-02-17T21:56:22Z",
    "message": "GPTBot verified from New York, US"
  },
  ...
]
GET/api/v1/public/norad/risk-map

Risk Map

Geographic risk distribution. Shows which countries have the highest density of bot activity and threat risk scores. Use for heatmap visualizations.

RESPONSE
[
  {
    "country_code": "US",
    "event_count": 28,
    "risk_score": 3.5
  },
  ...
]
GET/api/v1/public/norad/threats

Threat Intelligence

Active threat intelligence feed. Known malicious skills, suspicious behavior patterns, and bot threat classifications. Updated continuously from global monitoring.

RESPONSE
[
  {
    "skill_hash": "sha256:...",
    "threat_type": "content-scraping",
    "severity": "medium",
    "count": 5,
    "description": "Automated content extraction",
    "last_seen": "2026-02-17T20:00:00Z"
  },
  ...
]
GET/api/v1/public/norad/skills

Skill Analysis

AI agent skill distribution analysis. Shows which capabilities (web scraping, code execution, file access, etc.) are most common across detected bots. Includes suspicious skill flagging.

RESPONSE
{
  "total_unique_skills_detected": 12,
  "skill_distribution": [
    { "skill": "web_browsing", "count": 45, "bots_with_skill": 8 }
  ],
  "suspicious_skills": [],
  "challenge_response_rate": "0%",
  "bots_supporting_aps": 0,
  "bots_without_aps": 7
}

INGEST ENDPOINT

Report bot detections from your website to the NORAD global network. Available through our WordPress/Joomla plugins or direct API integration.

POST/api/v1/public/norad/ingest

Report Bot Detection

Submit a bot detection event. Used by SiteTrust.js client-side detector and CMS plugins. Bot type is matched against NORAD's signature database of 35+ known AI bots for automatic enrichment with organization, category, known skills, and risk assessment.

RESPONSE
// Request Body:
{
  "site_id": "your-site-id",
  "bot_type": "GPTBot",
  "user_agent": "Mozilla/5.0 ... GPTBot/1.2 ...",
  "decision": "allow",
  "page_url": "https://example.com/page",
  "ip_hash": "ip-abc123"
}

// Response:
{ "status": "ok", "country": "US", "city": "San Francisco" }

INTEGRATION EXAMPLES

Python — Monitor AI Bots

import requests

events = requests.get("https://api.clawbotden.com/api/v1/public/norad/live").json()

for event in events:
    if event["bot_type"] in ["GPTBot", "ClaudeBot", "PerplexityBot"]:
        print(f'{event["bot_type"]} from {event["city"]}, {event["country_code"]}')

JavaScript — Live Dashboard Widget

const res = await fetch("https://api.clawbotden.com/api/v1/public/norad/stats");
const stats = await res.json();
console.log(`Bots tracked (24h): ${stats.bots_tracked_24h}`);
console.log(`Threats detected: ${stats.threats_detected}`);

cURL — Check Active Bot Types

curl -s https://api.clawbotden.com/api/v1/public/norad/bot-types | jq '.[] | "\(.bot_type): \(.count)"'

DETECTION METHODS

NORAD uses a three-layer detection system to identify AI bots visiting protected websites:

LAYER 1: PASSIVE

User-Agent pattern matching against 35+ known AI bot signatures. Detects GPTBot, ClaudeBot, PerplexityBot, Bytespider, and more. Zero-latency, server-side.

LAYER 2: BEHAVIORAL

Client-side JavaScript fingerprinting via SiteTrust.js. Detects headless browsers, automation frameworks (Playwright, Puppeteer, Selenium), and bots with spoofed User-Agents.

LAYER 3: CHALLENGE

APS Safety Challenges embedded in HTML. AI agents that support the Agent Passport Standard voluntarily report their capabilities, enabling transparent bot identification.

← PROTECT YOUR SITEAI BOT DATABASE →