BotReveal API Reference

Authentication

All endpoints, other than the health check, are protected with API Authentication.

If you ever receive a 401 Unauthorized response, you need to set the Authorization header as below:

Authorization:Bearer customer-id:api-key

For example, if your HUMAN Customer ID is 12345 and your API Key is 2a8988a2-e4be-401e-b723-76eea886f3df, you can use cURL to call the the following:

curl https://kadati.p.botx.us -H "Authorization: Bearer 12345:2a8988a2-e4be-401e-b723-76eea886f3df"

With the Python Requests library, you'd call the following:

headers = {"Authorization": "Bearer 12345:2a8988a2-e4be-401e-b723-76eea886f3df"}

requests.get("https://kadati.p.botx.us", headers=headers)

Throughout this reference guide, we'll use the example Customer ID with a value of 12345 and the example API Key 2a8988a2-e4be-401e-b723-76eea886f3df.

How to obtain an API Key

To obtain your unique API Key, reach out to a HUMAN representative.

API Endpoints

Method URL Description
GET /health Returns a 200 response in request to health status.
POST /v1/iprisk/ Returns IP risk data based on the user's contracted schema.

health

Returns an OK 200 response to show the API is healthy

URL

GET /health

Success response

Code Description
200 OK

iprisk

Returns IP risk data of one or more IP addresses; the response is based on the user's contracted
schema.

URL

POST /v1/iprisk/

Success response

Code Description
200 OK

Unauthorized response

Code Description
401 Unauthorized

Bad request

Code Description
400 Bad request

Request payload

The API takes a JSON payload that consists of a single key called ips whose value is an array of IPv4 IP addresses. This payload is formatted like the following example:

{
    "ips": [
        "23.227.141.45",
        "73.61.8.166",
        "188.166.254.234"
    ]
}

However, if you send a request for a single IP address, this IP address would still be enclosed within an array:

{
    "ips": [
        "23.227.141.45"
    ]
}

Payload limits

There is an enforced limit on the number of IP addresses you can query in a single request. This is currently set to 10,000 IP addresses. If you try to request more than that in a single request, the API returns a 400 Bad Request response.

Note that latency increases with the number of IP addresses sent per request. For example, if you send a payload that includes 10,000 IP addresses, you should expect latency of about 10 to 20 seconds.

Sample request

Using CURL from the command line, you would make a request as below:

curl -s POST https://kadati.p.botx.us/v1/iprisk/ \
     -H 'Authorization: Bearer 12345:2a8988a2-e4be-401e-b723-76eea886f3df' \
     -H 'Content-Type: application/json' \
     -d '{"ips": ["23.227.141.45", "73.61.8.166", "188.166.254.234"]}'

with Python Requests library, as a full example, you'd call:

import requests

payload = {"ips": ["23.227.141.45", "73.61.8.166", "188.166.254.234"]}
headers = {"Authorization": "Bearer 12345:2a8988a2-e4be-401e-b723-76eea886f3df"}

response = requests.post("https://kadati.p.botx.us/v1/iprisk/", headers=headers, json=payload)
print(response.status_code)   # 200
print(response.json())  # [{'ip': '23.227.141.45', 'iab_crawler_rate': 0.07, 'last_seen_date':  ...

Response body

The response is based on the user's contracted schema.

All IP addresses that match the requested payload IP addresses will be included in the response. If there are no matching IP addresses, then an empty array [] will be returned.

Note: in the examples shown below, we assume we've queried for the three IP addresses shown above, but there are only two matches in the API's records that match, so only two results are ever shown.

For BotVerify customers, the response will be as follows:

  • IP address being queried
  • IAB crawler rate (as a percentage from 0 to 100)
  • Date last seen

For example:

[
  {
    "ip": "23.227.141.45",
    "iab_crawler_rate": 0.07,
    "last_seen_date": "2022-05-11"
  },
  {
    "ip": "188.166.254.234",
    "iab_crawler_rate": 0,
    "last_seen_date": "2022-05-11"
  }
]

For AttackTracker customers, the response will be as follows:

  • IP address being queried
  • IAB crawler rate (as a percentage from 0 to 100)
  • Date last seen
  • Bot probability (insufficient data, low, medium, high, critical)
  • IP classification (Residential, Hosting, Mobile, Unclassified)

For example:

[
  {
    "ip": "23.227.141.45",
    "iab_crawler_rate": 0.07,
    "last_seen_date": "2022-05-11",
    "bot_probability": "medium",
    "ip_classification": "Hosting"
  },
  {
    "ip": "188.166.254.234",
    "iab_crawler_rate": 0,
    "last_seen_date": "2022-05-11",
    "bot_probability": "low",
    "ip_classification": "Hosting"
  }
]

For BotInvestigator customers, the response will be as follows:

  • IP address being queried
  • IAB crawler rate (as a percentage from 0 to 100)
  • Date last seen
  • Bot probability (insufficient data, low, medium, high, critical)
  • IP classification (Residential, Hosting, Mobile, Unclassified)
  • Operating system (array of observed values, could be an empty array)
  • User Agent (array of observed values, could be an empty array)

For example:

[
  {
    "ip": "23.227.141.45",
    "iab_crawler_rate": 0.07,
    "last_seen_date": "2022-05-11",
    "bot_probability": "medium",
    "ip_classification": "Hosting",
    "os": [
      "Windows:10",
      "Windows:8.1",
      "Windows:7",
      "Mac OS X:10.15.7",
      "Linux:null",
      "Mac OS X:10.13.6"
    ],
    "ua": [
      "Firefox:100",
      "Chrome:100",
      "Chrome:101",
      "Chrome:94",
      "Chrome:86"
    ]
  },
  {
    "ip": "188.166.254.234",
    "iab_crawler_rate": 0,
    "last_seen_date": "2022-05-11",
    "bot_probability": "low",
    "ip_classification": "Hosting",
    "os": [
      "Android:10",
      "Android:12"
    ],
    "ua": [
      "Chrome Mobile:100",
      "Chrome Mobile:78"
    ]
  }
]

For ThreatHunter customers, the response will be as follows:

  • IP address being queried
  • IAB crawler rate (as a percentage from 0 to 100)
  • Date last seen
  • Bot probability (insufficient data, low, medium, high, critical)
  • IP classification (Residential, Hosting, Mobile, Unclassified)
  • Operating system (array of observed values, could be an empty array)
  • User Agent (array of observed values, could be an empty array)
  • Threat category (array of observed values: Known Spider or Crawler, Sophisticated Bot, Anonymized User, Abnormal Entity Behavior, Bad entity reputation, Anomalous Device)

For example:

[
  {
    "ip": "23.227.141.45",
    "iab_crawler_rate": 0.07,
    "last_seen_date": "2022-05-11",
    "bot_probability": "medium",
    "ip_classification": "Hosting",
    "os": [
      "Windows:10",
      "Windows:8.1",
      "Windows:7",
      "Mac OS X:10.15.7",
      "Linux:null",
      "Mac OS X:10.13.6"
    ],
    "ua": [
      "Firefox:100",
      "Chrome:100",
      "Chrome:101",
      "Chrome:94",
      "Chrome:86"
    ],
    "threat_category": [
      "Anonymized User",
      "Abnormal Entity Behavior",
      "Botnets",
      "Anomalous Device"
    ]
  },
  {
    "ip": "188.166.254.234",
    "iab_crawler_rate": 0,
    "last_seen_date": "2022-05-11",
    "bot_probability": "low",
    "ip_classification": "Hosting",
    "os": [
      "Android:10",
      "Android:12"
    ],
    "ua": [
      "Chrome Mobile:100",
      "Chrome Mobile:78"
    ],
    "threat_category": [
      "Anonymized User",
      "Bad entity reputation"
    ]
  }
]

Bot Probability category definitions

For all API responses that return a Bot Probability category, the definitions are as follows:

Bot Probability Definition
Insufficient Data Not enough traffic seen from this IP address to make a determination.
Low No evidence of compromise; less than 2% of the traffic from this IP shows signs of automation.
Medium Medium risk; up to 10% of traffic from this IP is classified as bot traffic.
High High risk; up to 20% of traffic from this IP is classified as bot traffic.
Critical Critical risk; Over 20% of the traffic from this IP is classified as bot traffic.