API Access Information
API Access Information
How to get access to the API
1. Authorization (getting a token):
curl -s -d ‘{“username”:”youremailaddress”, “password”:”yourreputationportalpassword”, “realm”:”nop”}’ https://api.spamhaus.org/api/v1/login
2. Getting the list of available files (remove [your token] with the Authorization result):
curl -s https://api.spamhaus.org/api/nop/v1/byobject/bailiwick/list -H ‘Authorization: Bearer [your token]’
For example you could have a file listing that looks like the following:
“type”:”list.json”,”dataset”:”XBL”,”bailiwick”:”example.com”,”size”:341},{“scope”:”ipv4″,”key”:”archive-202212021302/example.com/XBL/ipv4/”
3. Once you have the file list you can download one of the files using the file key as follows:
curl -s https://api.spamhaus.org/api/nop/v1/byobject/bailiwick/file/archive-202212021302/example.com/XBL/ipv4/17f7ccbe-0fbe-48a9-b856-a9f0841162e5 -H ‘Authorization: Bearer [your token]’
Available files list
- GET /byobject/bailiwick/list
- GET /byobject/bailiwick/list[?scope=][&type=][&dataset=][&bailiwick=]
This call is used to get files list available for the current user.
Output sample:
“`
{
“code”: 200,
“createts”: 1634733546,
“expirets”: 1634755146,
“files”: [
{
“scope”: “ipv4”,
“key”: “archive-202110201239/ovh.net/XBL/ipv4/3a29b077-59bd-4ace-9866-759d151930e7”,
“type”: “list.json”,
“dataset”: “XBL”,
“bailiwick”: “ovh.net”,
“size”: 4774675
},
{
“scope”: “ipv4”,
“key”: “archive-202110201239/ovh.net/XBL/ipv4/4a293457-59bd-4ace-8866-759d151930e7”,
“type”: “list.csv”,
“dataset”: “XBL”,
“bailiwick”: “ovh.net”,
“size”: 4355
},
{
“scope”: “ipv6”,
“key”: “archive-202111080600/amazon.com/ipv6/8ed86219-e916-4e79-a447-b405aa440b77”,
“type”: “summary”,
“bailiwick”: “amazon.com”,
“size”: 245
}
…
}
“`
- createts – index creation timestamp
- expirets – index expire timestamp
- files – available files list
- files.scope – data scope (ipv4/ipv6)
- files.key – file key. This can be used to download the file.
- files.type – file type. it can be list.json (submissions list in json format), list.csv (submissions list in simplified csv format) or summary (submissions IP addresses summary file, grouped by bailiwick; it contains all datasets available)
- files.dataset  file dataset (XBL,CSS,BCL) (available for list files only)
- files.size file size, in bytes
List files can be filtered by using one or more GET arguments.
Accepted filter arguments are: scope, type, dataset, bailiwick. Multiple search values can be passed as a comma separated argument.
- scope – filter using specified scope string (ipv4, ipv6).
- type – filter using specified type string (list.csv, list.json, summary).
- dataset – filter using specified dataset string (XBL…), if applicable (for example summary files are not related to a specific dataset).
- bailiwick –filter using specified bailiwick string (filters will be applied to available bailiwicks as resulting from user’s permissions).
Examples:
- GET /byobject/bailiwick/list?type=summary
Get ‘summary’ files.
- GET /byobject/bailiwick/list?dataset=XBL,CSS&bailiwick=amazon.com&type=list.csv
Get ‘csv’ files from XBL and CSS datasets, filtering by amazon.com bailiwick.
File download
- GET /byobject/bailiwick/file/(:filekey)
This call is used to download the dataset file. You must pass the (:filekey) obtained from the ‘list’ call.
Example:
- GET /byobject/bailiwick/file/archive-202110201239/ovh.net/XBL/ipv4/3a29b077-59bd-4ace-9866-759d151930e7
Available bailiwicks networks
- GET /byobject/bailiwick/networks
This call is used to get bailiwicks networks list available for the current user.
Output sample:
“`
{
“code”: 200,
“createts”: 1634733546,
“expirets”: 1634755146,
“items”:{
“amazon.com”:{
“AS14618”:[“3.5.0.0/20″,”3.5.0.0/24”,…],
“AS16509”:[“2.255.191.0/24″,”3.0.0.0/15″,”3.2.0.0/24”,…],
…
},
…
}
}
“`
- createts – index creation timestamp
- expirets – index expire timestamp
- items –available bailiwicks networks list grouped by network / ASN