NAV Navbar
shell

Introduction

The AbuseIPDB API allows you to utilize our database programmatically. This is most commonly done through Fail2Ban, which comes prepackaged with an AbuseIPDB configuration. Grab a new API key at from account dashboard.

Configuring Fail2Ban

actionban = curl --fail 'https://api.abuseipdb.com/api/v2/report' \
    -H 'Accept: application/json' \
    -H 'Key: <abuseipdb_apikey>' \
    --data-urlencode 'comment=<matches>' \
    --data-urlencode 'ip=<ip>' \
    --data 'categories=<abuseipdb_category>'

Follow our APIv1 tutorial. APIv2 works the same way except for slight alterations to the cURL request. In APIv2, actionban command in Fail2Ban's abuseipdb.conf will looks like:

That's it! You've migrated.

CHECK Endpoint

# The -G option will convert form parameters (-d options) into query parameters.
# The CHECK endpoint is a GET request.
curl -G https://api.abuseipdb.com/api/v2/check \
  --data-urlencode "ipAddress=118.25.6.39" \
  -d maxAgeInDays=90 \
  -d verbose \
  -H "Key: $YOUR_API_KEY" \
  -H "Accept: application/json"

This will yield the following JSON response:

  {
    "data": {
      "ipAddress": "118.25.6.39",
      "isPublic": true,
      "ipVersion": 4,
      "isWhitelisted": false,
      "abuseConfidenceScore": 100,
      "countryCode": "CN",
      "countryName": "China",
      "usageType": "Data Center/Web Hosting/Transit",
      "isp": "Tencent Cloud Computing (Beijing) Co. Ltd",
      "domain": "tencent.com",
      "totalReports": 1,
      "lastReportedAt": "2018-12-20T20:55:14+00:00",
      "reports": [
        {
          "reportedAt": "2018-12-20T20:55:14+00:00",
          "comment": "Dec 20 20:55:14 srv206 sshd[13937]: Invalid user oracle from 118.25.6.39",
          "categories": [
            18,
            22
          ],
          "reporterId": 1,
          "reporterCountryCode": "US",
          "reporterCountryName": "United States"
        }
      ]
    }
  }

The check endpoint accepts a single IP address (v4 or v6). Optionally you may set the maxAgeInDays parameter to only return reports within the last x amount of days.

The desired data is stored in the data property. Here you can inspect details regarding the IP address queried, such as version, country of origin, usage type, ISP, and domain name. And of course, there is the valuable abusive reports.

The isWhitelisted property reflects whether the IP is spotted in any of our whitelists. Our whitelists give the benefit of the doubt to many IPs, so it generally should not be used as a basis for action. The abuseConfidenceScore is a better basis for action, because it is nonbinary and allows for nuance. The isWhitelisted property may be null if a whitelist lookup was not performed.

The maxAgeInDays parameter determines how far back in time we go to fetch reports. In this example, we ask for reports no older than 90 days. The default is 30.

Reports are included in this response because the verbose flag was added. Omitting the verbose flag will exclude reports and the country name field. If you want to keep your response payloads light, this is recommended.

The IP address should be url-encoded, because IPv6 addresses use colons, which are reserved characters in HTTP requests.

Check Parameters

field required default min max
ipAddress yes
maxAgeInDays no 30 1 365
verbose no

BLACKLIST Endpoint

# The -G option will convert form parameters (-d options) into query parameters.
# The CHECK endpoint is a GET request.
curl -G https://api.abuseipdb.com/api/v2/blacklist \
  -d countMinimum=15 \
  -d maxAgeInDays=60 \
  -d confidenceMinimum=90 \
  -H "Key: $YOUR_API_KEY" \
  -H "Accept: application/json"

This will yield the following JSON response:

{
  "meta": {
    "generatedAt": "2018-12-21T16:00:04+00:00"
  },
  "data": [
    {
      "ipAddress": "5.188.10.179",
      "totalReports": 560,
      "abuseConfidenceScore": 100
    },
    {
      "ipAddress": "185.222.209.14",
      "totalReports": 529,
      "abuseConfidenceScore": 100
    },
    {
      "ipAddress": "191.96.249.183",
      "totalReports": 325,
      "abuseConfidenceScore": 100
    }
  ]
}

The blacklist is the culmination of all of the valiant reporting by AbuseIPDB users. It's a list of the most reported IP addresses.

The body is an array where each element contains the IP address, the total number of reports, and our confidence of abuse score.

We recommend you filter by abuseConfidenceScore, which is our calculated evaluation on how abusive the IP is based on the users that reported it (more). We place a hard minimum of 25% on the abuseConfidenceScore. There are two critical reasons for this:

  1. To prevent a handful of reports drastically impacting networks. If an AbuseIPDB user were to implement a blacklist that includes <25%-rated IPs, their network protocol would easily be swayed by a single or few third-party users. We recommend against the minimum of 25% for most applications. 75%-100% is the recommended range for denial of service.

  2. Performance. A <25% range is a wide net that would match the vast majority of our database. There are simply too many results for it to be performant or useful.

However, you can also filter by raw report count using countMinimum, which effectively gives every distinct reporter an equal weight. There is a hard minimum of 10 reports for the same reasons above.

The maxAgeInDays parameter determines how far back in time we go to fetch reports counted for the countMinimum parameter. In this example, we ask for reports no older than 60 days. The default is 30.

In the meta block we include generatedAt property that lets you check for the freshness of the list, if you'd like.

Subscribers may set the self flag, which configures the blacklist generator to only consider reports from their own account.

Plaintext Blacklist

curl -G https://api.abuseipdb.com/api/v2/blacklist \
  -d countMinimum=15 \
  -d maxAgeInDays=60 \
  -d confidenceMinimum=90 \
  -d plaintext \
  -H "Key: $YOUR_API_KEY" \
  -H "Accept: application/json"

or


curl -G https://api.abuseipdb.com/api/v2/blacklist \
  -d countMinimum=15 \
  -d maxAgeInDays=60 \
  -d confidenceMinimum=90 \
  -H "Key: $YOUR_API_KEY" \
  -H "Accept: text/plain"

to receive

5.188.10.179
185.222.209.14
95.70.0.46
191.96.249.183
115.238.245.8
122.226.181.164
122.226.181.167
...

If you prefer a simple newline-separated plaintext response. Set the plaintext flag via a GET flag or the Accept header.

The generation timestamp will be placed in the HTTP response headers as X-Generated-At.

Blacklist Caching

By default, the blacklist with default parameters is cached for one day. Results for premium subscribers are cached for one hour. The generatedAt property is the cache timestamp.

Blacklist IP Truncation

To conserve bandwidth, the number of IP addresses included in the list is capped to 10,000. Subscribers can overcome this limit. All users can set it between 1 and 10,000 using the limit parameter.

Blacklist Parameters

field required default min max subscriber feature
maxAgeInDays no 30 1 365 yes
countMinimum no 10 10 1000 yes
confidenceMinimum no 100 25 100 yes
limit no 10,000 1 restricted, see above
plaintext no
self

REPORT Endpoint

# POST the submission.
curl https://api.abuseipdb.com/api/v2/report \
  --data-urlencode "ip=127.0.0.1" \
  -d categories=18,22 \
  --data-urlencode "comment=SSH login attempts with user root." \
  -H "Key: $YOUR_API_KEY" \
  -H "Accept: application/json"

Response:

  {
    "data": {
      "ipAddress": "127.0.0.1",
      "abuseConfidenceScore": 52
    }
  }

Reporting IP addresses is the core feature of AbuseIPDB. When you report what you observe, everyone benefits, including yourself. To report an IP address, send a POST request. At least one category is required, but you may add additional categories using commas to separate the integer IDs. Related details can be included in the comment field.

In the body, we get the updated abuseConfidenceScore.

Report Parameters

field default restrictions description
ip required A valid IPv4 or IPv6 address.
categories required 30 Comma separated values; Reference
comment Related information (server logs, timestamps, etc.)

Test IP Addresses


  {
    "errors": [
      {
        "detail": "You can only report the same IP address (`127.0.0.2`) once in 15 minutes.",
        "status": 429,
        "source": {
          "parameter": "ip"
        }
      }
    ]
  }

Reporting 127.0.0.2 will simulate a short term rate limit. This is useful for application testing.

BULK-REPORT Endpoint

If reporting IP addresses one by one may not seem efficient to you, we offer an endpoint that allows a CSV file of IPs to be reported in one shot. Such a list can be extracted from your secure log file or similar. See the bulk report form for a guide.

# POST the submission.
curl https://api.abuseipdb.com/api/v2/bulk-report \
  -F csv=@report.csv \
  -H "Key: $YOUR_API_KEY" \
  -H "Accept: application/json" \
  > output.json

The response will inform you how many IPs were successfully reported, and which ones were rejected and why.

  {
    "data": {
      "savedReports": 60,
      "invalidReports": [
        {
          "error": "Duplicate IP",
          "input": "41.188.138.68",
          "rowNumber": 5
        },
        {
          "error": "Invalid IP",
          "input": "127.0.foo.bar",
          "rowNumber": 6
        },
        {
          "error": "Invalid Category",
          "input": "189.87.146.50",
          "rowNumber": 8
        }
      ]
    }
  }

API Daily Rate Limits

With the request header "Accept: application/json"

{
  "errors": [
      {
          "detail": "Daily rate limit of 1000 requests exceeded for this endpoint. See headers for additional details.",
          "status": 429
      }
  ]
}

Useful response headers

# Retry-After - Seconds a client should wait until a retry.
# X-RateLimit-Limit - Your daily limit.
# X-RateLimit-Remaining - Remaining requests available for this endpoint.
# X-RateLimit-Reset - The epoch timestamp for the daily limit reset.

Retry-After → 29241
X-RateLimit-Limit → 1000
X-RateLimit-Remaining → 0
X-RateLimit-Reset → 1545973200

The API daily rate limits are currently as follows:

Standard Webmaster Supporter Basic Subscription Premium Subscription
check 1,000 3,000 5,000 10,000 50,000
blacklist 5 10 20 100 500
report 1,000 1,000 1,000 10,000 50,000
check-block 100 250 500 1,000 5,000
bulk-report 5 10 20 100 500

Upon reaching your daily limit, you will receive a HTTP 429 Too Many Requests status.

By default, you receive an entire HTML page, which is why you should set "Accept: application/json" when working with the API programmatically.

Error Handling


  {
    "errors": [
      {
        "detail": "The max age in days must be between 1 and 365.",
        "status": 422
      }
    ]
  }

HTTP status codes are the most reliable method of determining the status of the API response. After all, that is the sole purpose of the codes. When we encounter at least one application error, a JSON response with a collection of errors is returned. The structure conforms to the JSON API spec:

At minimum, we will always include the the detail and status members. We may provide more members, as per the spec.

Security

All requests to the AbuseIPDB website and API must run over HTTPS. If a HTTP unsecure protocol is requested, it will be redirected to HTTPS via 302 Found.

While we accept your key as either a query parameter/form parameter or header, the header form is recommended. Why? Although HTTPS will encrypt the entire query string, server logs (like ours) will record them. And your infrastructure may have outgoing logging you are unaware of. You are responsible for account(s) compromised this way.

AbuseIPDB support will never ask you for your API key, nor your account password. We may only ask for your user id.