API documentation
Read access is public and returns JSON. Write access (feeding new detections) requires an API key. Base URL: https://www.blocklist.heinsen-it.de
Read endpoints (public)
| Endpoint | Description | Parameters |
|---|---|---|
GET/api or /api/list | Paginated threat list | page, limit (max 100), search, threat_filter (critical|high|medium|low), country_filter (ISO code), min_threat (1–99), days, sort_by (ip_address, first_seen, last_seen, threat_level, sightings, location, country_code), sort_dir, format=csv |
GET/api/stats | Totals by category, activity of the last 7 days, top countries, daily trend | – |
GET/api/ip | Details and activity log of one address | ip (required) |
GET/api/activity | Recent activity log | ip_id, limit (max 100) |
GET/export | Plain-text blocklist (one IP per line, comment header) for firewalls and IDS | min (threat level, default 60), category, days, download |
GET/export/csv, /export/json | Same selection as CSV or JSON | as above |
Examples
curl "https://www.blocklist.heinsen-it.de/api?threat_filter=critical&limit=50" curl "https://www.blocklist.heinsen-it.de/api/ip?ip=203.0.113.5" curl "https://www.blocklist.heinsen-it.de/export?min=75" -o blocklist.txt
Response format
{
"status": "success",
"timestamp": "2026-09-13 18:00:00",
"pagination": { "page": 1, "limit": 20, "total_count": 3412, "total_pages": 171 },
"ips": [
{ "id": 3415, "ip": "203.0.113.5", "first_seen": "2026-09-13 17:28:22", "last_seen": "2026-09-13 17:28:22",
"threat_level": 55, "threat_category": "medium", "sightings": 1, "location": null, "country_code": "DE",
"isp": null, "notes": null, "created_at": "...", "updated_at": "..." }
]
}
Write endpoints (API key required)
Send the key as X-Api-Key: <key> or Authorization: Bearer <key>. Keys are configured per source; the source name is recorded with every event. Bodies are JSON.
| Endpoint | Description | Body |
|---|---|---|
POST/api/add | Report a detection. Existing addresses get +1 sighting and keep the highest threat level. | ip*, threat_level* (1–99), location, country_code, isp, notes, activity_type (scan, attack, brute_force, web_attack, spam …), severity, source, description, metadata (object), detected_at (ISO 8601 or unix time) |
POST/api/bulk | Up to 500 detections in one request | threats: array of the objects above (optional defaults threat_level, activity_type at top level) |
POST/api/activity | Log an event for an address (threat level optional) | as /api/add |
POST/api/status | Activate/deactivate an address (deactivated = removed from list and exports) | ip*, is_active |
POST/api/sync | Forward pending addresses to the AbuseIPDB reporter platform | limit, dry_run=1 (query parameters) |
GET/api/sync | Forwarding status (pending, forwarded, last run) | – |
Example
curl -X POST "https://www.blocklist.heinsen-it.de/api/add" \
-H "X-Api-Key: YOUR_KEY" -H "Content-Type: application/json" \
-d '{
"ip": "203.0.113.5",
"threat_level": 75,
"activity_type": "brute_force",
"source": "WordPress-Firewall",
"description": "12 failed logins on wp-login.php",
"country_code": "DE",
"metadata": {"wordpress_site": "https://example.org", "detection_method": "log_analysis"}
}'
Detections are forwarded automatically to the AbuseIPDB reporter platform (if configured), including threat level, country, ISP, source and metadata. There, an administrator reviews the entries and reports them to AbuseIPDB.
Threat levels
| Category | Threat level | Meaning |
|---|---|---|
| critical | 90 – 99 | Confirmed attacks, repeated abuse from the same address |
| high | 70 – 89 | Attack attempts (brute force, exploits, injection) |
| medium | 40 – 69 | Scans, probing, suspicious bot activity |
| low | 1 – 39 | Minor anomalies, single observations |
Rate limits: please cache list responses for at least 60 seconds and use /export for full blocklists instead of paging through the API.