API Documentation - AbuseIPDB

APIv1 is deprecated in favor of APIv2. The sunset date is . Support tickets for APIv1 will not receive responses, except under special circumstances. This page will remain here for archival purposes.

AbuseIPDB provides a free API for reporting and checking IP addresses. Every day webmasters, system administrators, and other IT professionals use our API to report thousands of IP addresses engaging spamming, hacking, vulnerability scanning, and other malicious activity in real time.

This API allows you to protect your network by checking IP addresses against our database and allows you to contribute by submitting malicious IP addresses that you detect. The API is free to use, but you do have to create an account.

If you are a webmaster or sysadmin interested in automatically reporting abusive IPs via the AbuseIPDB API, we recommend you also see the Fail2Ban integration tutorial.

API Endpoints

Both GET and POST methods may be used.

Check IP

https://www.abuseipdb.com/check/[IP]/json?key=[API_KEY]&days=[DAYS]

Check CIDR

https://www.abuseipdb.com/check-block/json?network=[CIDR]&key=[API_KEY]&days=[DAYS]

Report IP

https://www.abuseipdb.com/report/json?key=[API_KEY]&category=[CATEGORIES]&comment=[COMMENT]&ip=[IP]

Parameters Explained

FieldRequiredDefaultExampleDescription
[IP]YesNA8.8.8.8
::1
IPv4 or IPv6 Address
[DAYS]No3030Check for IP Reports in the last 30 days
[API_KEY]YesNATzmp1...quWvaiOYour API Key (Get an API Key)
[CATEGORIES]YesNA10,12,15Comma delineated list of category IDs (See all Categories)
[COMMENT]NoblankBrute forcing Wordpress loginDescribe the type of malicious activity
[CIDR]YesNA207.126.144.0/20IPv4 Address Block in CIDR notation
verbose flagNoFALSE/json?key=[API_KEY]&days=[DAYS]&verboseWhen set, reports will include the comment (if any) and the reporter's user id number (0 if reported anonymously)

Rate Limits

All free accounts have a rate limit of 1,000 reports and checks per day. Webmaster accounts have a rate limit of 3,000 requests/day. You can view your rate limits and API usage information by going to the accounts page page and clicking on the "API Usage" tab.

To prevent duplicate reports being submitted automatically through our API (such as via Fail2Ban integration), we limit each account to reporting the same IP once per 15 minutes. After 15 minutes, if the same IP is reported within a 24-hours window with the same comment, a new report is not created. Rather, the timestamp of the original report is updated.

Security

API Key

After registering, you can get your API key from the accounts page. Click on the "API Settings" tab to see your API key. You can generate a new API key at anytime. When you generate a new API key the old key will stop working immediately.

You should protect your API key like a password. Anyone who has access to your API key can submit reports on your behalf. You can pass your API key as a GET parameter, but for security reasons we recommend you pass your API key as a POST parameter.