Spamhaus Intelligence REST API

You can access Spamhaus Intelligence API (SIA) through a convenient HTTP REST interface, enabling real time access to IP and domain reputation data for the automated assessment and discovery of potential threats or changes.

The following is a list of all available endpoints and how to use them.

Login

To access the API, every request requires a proper Authorization header containing a specific token. Therefore, to get SIA access, you must pass the authentication stage.

To fetch your temporary token, send a request to the Login API, which you can access by sending a POST request to the /api/v1/login endpoint.

The POST payload should include a JSON object containing the username and the password, as set up in the customer portal, as the following example shows:

curl -s -d '
    {
	"username":"[email protected]",
	"password":"m4g1c",
	"realm":"intel"
    }' https://api.spamhaus.org/api/v1/login

  • username is the email address associated with your SIA account.

  • password is the SIA password assigned to such user.

  • realm is -as far SIA is involved- always intel

In the case of success, the HTTP status code will be 200 and the body will contain a JSON object similar to the following one:

{
  "code": 200,
  "token": "eyJ0eXAi[......]dx2UTSGcyEKvU",
  "expires": 1583252180
}

The successful JSON response object will include an “expires” integer field detailing the Unix timestamp of when the token will expire. Usually, each token is valid for 24 hours.

In the case of authentication failure, the API will return a different status code and an associated error message as part of the JSON object:

{
  "code": 401,
  "message": "Authentication failed"
}

When an auth token has expired any subsequent API requests will result in a 401 Unauthorized HTTP response code. In this case, you require a new auth token before sending additional API requests. However, there is no need to wait until a token has expired before requesting a new one. We recommend refreshing the token when the current one is close to expiration.

NOTE: Please do NOT request an auth token for each API request. This action is penalized to protect against brute force attacks and may result in API access being temporarily slowed down or blocked. Additionally, this approach will slow the service due to the added latency introduced by the repeated authentication sessions.

The Authorization header

Once logged in, you must store the token value indicated in the response payload.

The token value is needed to assemble the authentication header . You need to add this header to every request to the API, excluding the login calls.

The Authorization header must be in the form:

Authorization: Bearer <AUTH TOKEN>

<AUTH TOKEN> is the string obtained through the previously described API call.

Please note that you should remove the < and > symbols. They are used in this example to contain the token placeholder. The full “” string should be replaced with the real token.

Limits and counters

Access to SIA limits the number of queries you can run over specified time frames. These limits are associated with the product tier that you have subscribed to. If you need to change these limits, please contact your sales representative.

The limits API endpoint allows you to check the maximum query limits applied to your account and the number of queries used for each limit, e.g. 24 hours and 30 days.

Usage example:

curl -sH 'Authorization: Bearer <AUTH TOKEN>' \
        https://api.spamhaus.org/api/intel/v1/limits

This api call returns a JSON object like this:

{
  "status": 200,
  "account": {
    "sub": "3534543",
    "usr": "[email protected]"
  },
  "limits": {
    "ads": "XBL,BCL,CSS",
    "trs": "base",
    "qms": 1000,
    "qmh": 1500,
    "rl_qph": 3600,
    "rl_qpm": 60,
    "rl_qps": 1
  },
  "current": {
    "qpm": 18,
    "qpd": 18,
    "rl_qph": 5,
    "rl_qpm": 0,
    "rl_qps": 0
  }
}

Field explanations:

  • code - will be 200 in the case of success; otherwise an error occurred

  • account - an object which shows the account properties:

    • sub - shows the account subscription identifier

    • usr - shows the account username

  • limits - an object containing the global limits of the account

    • ads - allowed queries datasets (comma separated list)

    • trs - identifier of the access level, defaults to “base”

    • qms - an integer showing the max number of queries per month allowed (soft limit)

    • qmh - an integer showing the max number of queries per month allowed (hard limit)

    • rl_qph - an integer showing the enforced rate limits (queries per hour)

    • rl_qpm - an integer showing the enforced rate limits (queries per minute)

    • rl_qps - an integer showing the enforced rate limits (queries per second)

  • current - an object containing the current counters of the account

    • qpm - shows the number of actual queries performed during the current month

    • qpd - shows the number of actual queries performed during the current day

    • rl_qph - an integer showing the rate limit current counter (queries per hour)

    • rl_qpm - an integer showing the rate limit current counter (queries per minute)

    • rl_qps - an integer showing the rate limit current counter (queries per second)

The rate limit values are predominantly intended as a measure to prevent abuse of the system that can cripple its functionalities. The contractual tier of the user is defined by qms and qmh. The soft limit is the contractually allowed number of queries per month. If you exceed these limits regularly, the account’s query volumes will need reviewing.

If the hard limit is reached, the system will refuse all subsequent queries with a 429 - Too many requests HTTP error code.

This same error message is provided if your query rate is too high and you are hitting one of the rate limit values (the various rl_qpX entries). If this is the case, please can we request you to add some delay between API calls to slow down your query rate?

The rate-limiting engine thresholds are proportional to the maximum number of daily queries your account can perform based on account type.

NOTE: Not all queries are counted as 1. Queries for CIDR resources have a multiplier applied relating to the size of the requested CIDR:

  • a query for a /32 IPv4 (or a /64 IPv6) is counted as 1

  • a query for a /31 IPv4 (or a /63 IPv6) is counted as 2

  • …

  • a query for a /24 IPv4 (or a /56 IPv6) is counted as 9

To calculate the “count” of a query for a CIDR, apply log2X where X is the number of distinct resources and add 1 (addresses in the case of IPv4, /64’s in the case of IPv6) contained in the CIDR.