BadBot Gateway API

Quickstart

Start with a health check, create or generate an API key, submit a report, then query reputation for the same indicator.

curl https://gateway.badbot.net/api/v1/health
# → {"status":"ok","time":"2026-05-12T10:00:00+00:00"}

export BADBOT_API_KEY="paste-your-key-here"

curl -X POST https://gateway.badbot.net/api/v1/report \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $BADBOT_API_KEY" \
  -d '{
    "indicator": "198.51.100.23",
    "category_id": 1,
    "severity": 6,
    "comment": "Credential stuffing"
  }'
# → {"status":"reported","id":42}

curl https://gateway.badbot.net/api/v1/reputation/198.51.100.23

Authentication

Submit Report

Submit a single abuse report for an IP address or domain.

Request body

curl -X POST https://gateway.badbot.net/api/v1/report \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $BADBOT_API_KEY" \
  -d '{
    "indicator": "198.51.100.23",
    "category_id": 1,
    "severity": 6,
    "comment": "Credential stuffing"
  }'

{
  "status": "reported",
  "id": 42
}

Bulk Report

Submit up to 1 000 reports in one request. The request body can be a JSON array or an object with a reports key. Each item uses the same fields as a single report. Invalid rows are collected in the errors array without blocking valid ones.

curl -X POST https://gateway.badbot.net/api/v1/report/bulk \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $BADBOT_API_KEY" \
  -d '[
    {"indicator":"198.51.100.23","category_id":1,"severity":6},
    {"indicator":"evil.example.com","category_id":9,"severity":8}
  ]'

{
  "created": 2,
  "errors": [],
  "total": 2
}

{
  "created": 1,
  "errors": [
    {"index": 1, "error": "Category 99 does not exist"}
  ],
  "total": 2
}

Reputation Lookup

Returns the reputation score, report count, category breakdown, and last report timestamp for an IP address or domain. Scores decay over time using a configurable half-life.

curl https://gateway.badbot.net/api/v1/reputation/198.51.100.23

{
  "indicator": "198.51.100.23",
  "found": true,
  "score": 42.5,
  "total_reports": 3,
  "categories": {
    "Credential Stuffing": 3
  },
  "last_reported_at": "2026-01-01T12:00:00+00:00",
  "allowlisted": false
}

When the indicator is unknown, found is false and score is 0.

Search Indicators

Prefix search across all known indicators with pagination, sorting, and optional country filter.

Query parameters

curl "https://gateway.badbot.net/api/v1/search?q=198.51&sort=recent&limit=5"

[
  "198.51.100.23",
  "198.51.100.44",
  "198.51.200.1"
]

Autocomplete Suggestions

Lightweight prefix search returning indicator values and types. Useful for search-as-you-type UIs. When q is omitted, returns the most recently reported indicators.

Query parameters

curl "https://gateway.badbot.net/api/v1/suggest?q=198.51&limit=3"

[
  {"value": "198.51.100.23", "type": "ip"},
  {"value": "198.51.100.44", "type": "ip"},
  {"value": "198.51.200.1", "type": "ip"}
]

Correlation

Find IP indicators related through shared ASN or subnet, passive DNS, and shared honeypot evidence (submitted credentials, client fingerprint, user agent). Currently supports IP addresses only.

curl https://gateway.badbot.net/api/v1/correlation/198.51.100.23

{
  "seed": {
    "indicator": "198.51.100.23",
    "type": "ip",
    "found": true,
    "score": 42.5,
    "total_reports": 3,
    "meta": {
      "asn": "64496",
      "organization": "Example ISP",
      "country": "US"
    }
  },
  "matches": [...],
  "infrastructure": {
    "meta": {...},
    "domains": [...]
  },
  "spread_summary": {...},
  "activity_timeline": [...]
}

The response includes correlated matches, passive DNS infrastructure, activity timelines, and regional spread data.

Feeds

Feeds are available through stable web aliases and the API route. Use TXT for simple blocklists, CSV for imports, and JSON for structured automation.

Stable web aliases

API route query parameters

curl "https://gateway.badbot.net/api/v1/feeds/high-risk?type=ipv4&min_score=10&limit=100"

{
  "indicator": "198.51.100.23",
  "score": 42.5,
  "reports": 3,
  "country_iso": "US",
  "asn": "64496"
}

Abuse Categories

Every report requires a category_id. The default severity is used when you omit the severity field.

Rate Limits

Every API and feed endpoint is rate-limited per client IP, with or without an API key. When a limit is exceeded the response is 429 Too Many Requests with a Retry-After header giving the seconds to wait.

Errors

Error responses use a consistent JSON shape. The HTTP status code is mirrored in the body.

{
  "error": "Bad Request",
  "message": "Category 99 does not exist",
  "status": 400
}

Code Examples

import os
import requests

base_url = "https://gateway.badbot.net"
api_key = os.environ["BADBOT_API_KEY"]

payload = {
    "indicator": "198.51.100.23",
    "category_id": 1,
    "severity": 6,
    "comment": "Credential stuffing",
}

response = requests.post(
    f"{base_url}/api/v1/report",
    json=payload,
    headers={"X-Api-Key": api_key},
    timeout=10,
)
response.raise_for_status()

reputation = requests.get(
    f"{base_url}/api/v1/reputation/{payload['indicator']}",
    timeout=10,
).json()
print(reputation)

const baseUrl = "https://gateway.badbot.net";
const apiKey = process.env.BADBOT_API_KEY;

const report = {
  indicator: "198.51.100.23",
  category_id: 1,
  severity: 6,
  comment: "Credential stuffing",
};

const response = await fetch(`${baseUrl}/api/v1/report`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": apiKey,
  },
  body: JSON.stringify(report),
});

if (!response.ok) {
  throw new Error(`BadBot API error ${response.status}`);
}

<?php
$baseUrl = 'https://gateway.badbot.net';
$apiKey = getenv('BADBOT_API_KEY');
$payload = json_encode([
    'indicator' => '198.51.100.23',
    'category_id' => 1,
    'severity' => 6,
    'comment' => 'Credential stuffing',
]);

$ch = curl_init($baseUrl . '/api/v1/report');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException('BadBot API error ' . $status . ': ' . $body);
}

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	payload, _ := json.Marshal(map[string]any{
		"indicator":   "198.51.100.23",
		"category_id": 1,
		"severity":    6,
		"comment":     "Credential stuffing",
	})

	req, _ := http.NewRequest("POST", "https://gateway.badbot.net/api/v1/report", bytes.NewReader(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-Api-Key", os.Getenv("BADBOT_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	if resp.StatusCode >= 400 {
		panic(resp.Status)
	}
}

Machine-Readable Docs

Use these endpoints for generated clients, API discovery, and agent-friendly context.

Terms of Use

• The API and feeds are free to use, including commercially, to protect your own networks, users and customers.
• Attribution (“Data: BadBot.net”) is appreciated, not required.
• Reselling the data, or redistributing it as (part of) a feed, dataset or product of your own, needs written permission from info [at] badbot.net.
• The data is provided as is, without warranty. A listing records abuse our honeypot sensors observed; test before you block.
• Listings expire on their own. To have one reviewed sooner, see delisting.