API REFERENCE

RESTful API documentation for programmatic access to the DNSBL Reporting Service. This service is completely free for all users.

AUTHENTICATION

API KEY AUTHENTICATION

All API requests require authentication using an API key. Include the key in the request header.

Authorization: Bearer YOUR_API_KEY

REQUEST API KEY

API keys are issued to cybersecurity professionals for advanced features including programmatic access, bulk lookups, and automated reporting. The service is completely free.

ENDPOINTS

IP LOOKUP

GET

/api/lookup?ip=ADDRESS

PARAMETERS

• ip (required) - IPv4 or IPv6 address to query

EXAMPLE REQUEST

curl -X GET "https://api.dnsbl.io/api/lookup?ip=2001:db8::1" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "found": true,
  "entries": [
    {
      "ip_address": "2001:db8::1",
      "ip_version": 6,
      "category": "ssh-attack",
      "severity": "high",
      "reason": "Multiple SSH brute force attempts",
      "report_count": 5,
      "first_reported_at": "2025-12-01T22:48:24.922Z",
      "last_reported_at": "2025-12-06T22:48:24.922Z"
    }
  ]
}

SUBMIT X-ARF REPORT

POST

/api/xarf

REQUEST BODY

X-ARF formatted JSON report (see X-ARF documentation)

EXAMPLE REQUEST

curl -X POST "https://dnsbl.io/api/xarf" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "Report-ID": "XARF-2025-001",
    "Report-Type": "abuse",
    "Category": "spam",
    "Source-IP": "2001:db8::bad:1",
    ...
  }'

EXAMPLE RESPONSE

{
  "success": true,
  "message": "X-ARF report processed successfully",
  "reportId": "uuid-here",
  "blacklistEntryId": "uuid-here"
}

BULK IP LOOKUP

POST

/api/lookup/bulk

REQUEST BODY

{
  "addresses": [
    "192.0.2.100",
    "2001:db8::1",
    "198.51.100.50"
  ]
}

Query multiple IP addresses in a single request. Maximum 100 addresses per request.

RATE LIMITS

The service is completely free with generous rate limits designed for professional cybersecurity use:

• 50,000 requests per day
• 100 requests per minute
• Bulk lookup enabled (up to 100 IPs per request)
• Full access to all API endpoints
• Unlimited DNS queries

If you require higher limits for large-scale operations, please contact us to discuss your use case.

HTTP RESPONSE CODES

• 200 OK - Request successful

• 400 Bad Request - Invalid parameters or malformed request

• 401 Unauthorized - Missing or invalid API key

• 404 Not Found - Resource not found

• 409 Conflict - Duplicate resource (e.g., Report-ID)

• 429 Too Many Requests - Rate limit exceeded

• 500 Internal Server Error - Server-side error