1. Description

This document is intended to serve software developers as an implementation guide for integration with Capture API.

Capture API provides verified data about peers activity in BitTorrent network in real time.

All peers collected via DHT are checking with set of Capture Filters for capturing. Capture Filter is the rule to define which peer should be captured. Basic attributes of Capture Filters:

  • infohashes - optional. List of torrent info hashes to capture

  • subnets - optional. List of subnets in CIDR format

  • countries - optional. List of country codes in ISO 3166-1 alpha-2

  • storeTCPDumpFile - optional. Should TCP dump be stored or not.

Capture Filter is created by our manager but you can managed it via this API. If peer should be captured then system connects to it via Bittorrent protocol, makes initial handshake and stores all captured data and TCP dump in Pcap format if needed. As the result you can receive it in realtime over email or RabbitMQ or request it via REST.

2. Connectivity

2.1. Connection type

Connection to Capture API is available over the HTTPS protocol based on REST. Every request that your application sends to the Capture API needs to contain API key as parameter key. Please request API key from your manager.

Realtime notifications are available over email or RabbitMQ.

2.2. Captured Peers History

You can get captured peers history by HTTP GET request:

  • host - hostname, will be provided.

  • from - from timestamp, in milliseconds.

  • to - desired to timestamp, in milliseconds.

  • filter - Capture Filter name, will be provided by your manager.

  • success - optional boolean (true/false), return only successfully/unsuccessfully captured peers.

  • key - API Key.

cURL examples:

# Request all data from 2018-06-16 21:00:00 UTC to 2018-06-17 21:00:00 UTC for Capture Filter yourFilterName
curl -X GET "https://{host}/capture/peers/all/?key=yourkey&from=1529182800000&to=1529269200000&filter=yourFilterName"

# Request successfully captured data from 2018-06-16 21:00:00 UTC to 2018-06-17 21:00:00 UTC for Capture Filter yourFilterName
curl -X GET "https://{host}/capture/peers/all/?key=yourkey&from=1529182800000&to=1529269200000&filter=yourFilterName&success=true"

Response format - Json, example:

  "from": 1529182800000,
  "to": 1529252207000000,
  "hasMore": false,
  "peers": [
      "date": "2018-06-17T05:58:36.000+0000",
      "ip": "",
      "port": 39716,
      "infohash": "d059053fd7122a95408346147b1edc0193432a0c",
      "countryCode": "RU",
      "city": "Vladivostok",
      "isp": "Joint Stock Company Artemovskoye Interaktivnoe Tel",
      "captureReport": {
        "date": "2018-06-17T05:59:01.000+0000",
        "totalPiecesInTorrent": 3053,
        "hasTotal": true,
        "hasPieces": 3053,
        "clientName": "BitTorrent 7.10",
        "hostIdentifier": "ipn-46-19-68-144.artem-catv.ru"
      "date": "2018-06-17T05:58:41.000+0000",
      "ip": "",
      "port": 51777,
      "infohash": "d059053fd7122a95408346147b1edc0193432a0c",
      "countryCode": "RU",
      "city": "Moscow",
      "isp": "Net By Net Holding LLC",
      "captureReport": {
        "date": "2018-06-17T05:58:47.000+0000",
        "totalPiecesInTorrent": 3310,
        "hasTotal": false,
        "hasPieces": 1784,
        "clientName": "libTorrent 0.13.2",
        "hostIdentifier": ""
Response JSON fields
Field Description


from timestamp in milliseconds


real to timestamp in milliseconds. Could be different from desired to timestamp from request


flag that there are more peers any you should repeat this request with from=real to and to=desired to


list of captured peers


datetime when peer was found in DHT, in UTC


ip address of peer


Bittorrent protocol port of peer


info hash of seeded torrent


ISO 3166-1 alpha-2 country code


approximate city of peer


approximate ISP of peer


optional, in case of successed capturing


time when capture report was done, in UTC


total pieces in torrent


how many pieces peer has


has peer all pieces (seeder) or not (leacher)


peer client name


peer reverse DNS name if known


error description if no CaptureReport

2.3. List of Capture Filters

You can get list of your Capture Filters by HTTP GET request:

  • key - API Key.

Response format - Json, example:

  "filters": [
      "name": "CaptureFilter1",
      "description": "Opensource OS",
      "infohashes": [
      "subnets": [],
      "countryCodes": [
      "storeTCPDumpFile": true,
      "storeTCPDumpAttempt": true,
      "enabled": true
Response JSON fields
Field Description


unique name of Capture Filter


human readable description of Capture Filter


list of info hashes of torrent to capture. Empty for all


list of CIDR subnets to capture. Empty for all


list of country codes to capture. Empty for all


should Pcap TCP dump be stored or not


should unsuccessful attepmt of capture be stored or not


is Capture Filter enabled

2.4. Add Info Hash to Capture Filter

You can add new Info Hash to your Capture Filter by HTTP POST request:

POST parameters
  • key - API Key.

  • filter - Capture Filter name.

  • infohash - Torrent info hash.

cURL example:

curl --data "key=yourKey&filter=yourFilterName&infohash=503c73b73405f950ae9f63555df9c6255acafcd0" https://{host}/capture/filters/addInfohash/

Response contains HTTP 200 OK and empty Json if added.

Our system should have info hash and downloaded and parsed torrent file before adding it to Capture Filter. It’s recommended to add torrent file with Add Torrent from TorrentAPI. Also you could add only info hash with Add Infohash method but in that case you have to wait while torrent file will be downloaded by our system.

2.5. Delete Info Hash from Capture Filter

You can delete Info Hash from your Capture Filter by HTTP POST request:

POST parameters
  • key - API Key.

  • filter - Capture Filter name.

  • infohash - Torrent info hash.

cURL example:

curl --data "key=yourKey&filter=yourFilterName&infohash=503c73b73405f950ae9f63555df9c6255acafcd0" https://{host}/capture/filters/deleteInfohash/

Response contains HTTP 200 OK and empty Json if deleted.

There are should be at least 1 info hash in Capture Filter, you cannot delete all info hashes from it.

2.6. HTTP response codes

  • 200 - OK

  • 500 - Internal server error

2.7. Error response

In case of error response body contains error and message:

    error: "API_KEY_UNKNOWN",
    message: "API Key is unknown",
possible error values (new can be added later)
  • API_KEY_UNKNOWN - API key is unknown

  • API_KEY_SUSPENDED - API key is suspended

  • ACCESS_FORBIDDEN - API key doen’t provide access to method

  • INVALID_INFOHASH - value of infohash is invalid

  • INFOHASH_NOT_FOUND - torrent with infohash not found in our database

  • TORRENT_FILE_NOT_FOUND - torrent file is not found for existed infohash in our database

  • FILTER_NOT_FOUND - Capture Filter not found

  • FILTER_WITHOUT_INFOHASHES_NOT_ALLOWED - Capture Filter should have at least one info hash