Download¶

With the download API you can control the download queue of the Freebox. The Freebox supports downloads from HTTP, FTP, Magnet link, .torrent files and newsgroups (NNTP). Each download task is represented by a Download object.

Download Errors¶

When attempting to access the download API, you may encounter the following errors:

error_code	Description
task_not_found	No task was found with the given id
invalid_operation	Attempt to perform an invalid operation
invalid_file	Error with the download file (invalid format ?)
invalid_url	URL is invalid
not_implemented	Method not implemented
out_of_memory	No more memory available to perform the requested action
invalid_task_type	The task type is invalid
hibernating	The downloader is hibernating
need_bt_stopped_done	This action is only valid for Bittorrent task in stopped or done state
bt_tracker_not_found	Attempt to access an invalid tracker object
too_many_tasks	Too many tasks
invalid_address	Invalid peer address
port_conflict	Port conflict when setting config
invalid_priority	Invalid priority
internal_error	Internal error
ctx_file_error	Failed to initialize task context file (need to check disk)
exists	Same task already exists
port_outside_range	Incoming port is not available for this customer (see `ConnectionStatus` ipv4_port_range)

Download Task / TaskFile Errors¶

Each download task can encounter one of the following errors:

Error Description

none No error

internal Internal error

disk_full The disk is full

unknown Unknown error

parse_error Parse error

http_301 HTTP 301 error

http_400 HTTP 400 error

http_401

http_402

http_403

http_404

http_405

http_406

http_407

http_408

http_409

http_410

http_411

http_412 [ ... ]

http_413

http_414

http_415

http_416

http_417

http_422

http_423

http_424

http_425

http_426

http_427

http_428

http_429

http_430

http_431

http_4xx Other 4xx HTTP errors

http_500 HTTP 500 error

http_501

http_502

http_503

http_504

http_505

http_506 [ ... ]

http_507

http_508

http_509

http_510

http_511

http_5xx Other 5xx HTTP errors

http_redirections_exceeded Too many HTTP redirections

nzb_no_group Cannot find the requested group on server

nzb_not_found Article not fount on the server

nzb_invalid_crc Invalid article CRC

nzb_invalid_size Invalid article size

nzb_invalid_filename Invalid filename

nzb_open_failed Error opening

nzb_write_failed Error writing

nzb_missing_size Missing article size

nzb_decode_error Article decoding error

nzb_missing_segments Missing article segments

nzb_error Other nzb error

unknown_host Unknown host

timeout Timeout

bad_authentication Invalid credentials

connection_refused Remote host refused connection

nzb_authentication_required Nzb server need authentication

bt_tracker_error Unable to announce on tracker

bt_missing_files Missing torrent files

bt_file_error Error accessing torrent files

missing_ctx_file Error accessing task context file

Error	Description
none	No error
internal	Internal error
disk_full	The disk is full
unknown	Unknown error
parse_error	Parse error
http_301	HTTP 301 error
http_400	HTTP 400 error
http_401
http_402
http_403
http_404
http_405
http_406
http_407
http_408
http_409
http_410
http_411
http_412	[ ... ]
http_413
http_414
http_415
http_416
http_417
http_422
http_423
http_424
http_425
http_426
http_427
http_428
http_429
http_430
http_431
http_4xx	Other 4xx HTTP errors
http_500	HTTP 500 error
http_501
http_502
http_503
http_504
http_505
http_506	[ ... ]
http_507
http_508
http_509
http_510
http_511
http_5xx	Other 5xx HTTP errors
http_redirections_exceeded	Too many HTTP redirections
nzb_no_group	Cannot find the requested group on server
nzb_not_found	Article not fount on the server
nzb_invalid_crc	Invalid article CRC
nzb_invalid_size	Invalid article size
nzb_invalid_filename	Invalid filename
nzb_open_failed	Error opening
nzb_write_failed	Error writing
nzb_missing_size	Missing article size
nzb_decode_error	Article decoding error
nzb_missing_segments	Missing article segments
nzb_error	Other nzb error
unknown_host	Unknown host
timeout	Timeout
bad_authentication	Invalid credentials
connection_refused	Remote host refused connection
nzb_authentication_required	Nzb server need authentication
bt_tracker_error	Unable to announce on tracker
bt_missing_files	Missing torrent files
bt_file_error	Error accessing torrent files
missing_ctx_file	Error accessing task context file

Download object¶

Download objects have the following attributes:

Download¶

id int Read-only¶: id

type enum Read-only¶

The valid download types are:

Type	Description
bt	bittorrent download
nzb	newsgroup download
http	HTTP download
ftp	FTP download

name string Read-only¶

status enum¶

The valid download status are:

Status	Description
stopped	task is stopped, can be resumed by setting the status to downloading
queued	task will start when a new download slot is available the queue position is stored in queue_pos attribute
starting	task is preparing to start download
downloading
stopping	task is gracefully stopping
error	there was a problem with the download, you can get an error code in the error field
done	the download is over. For bt you can resume seeding setting the status to seeding if the ratio is not reached yet
checking	(only valid for nzb) download is over, the downloaded files are being checked using par2
repairing	(only valid for nzb) download is over, the downloaded files are being repaired using par2
extracting	only valid for nzb) download is over, the downloaded files are being extracted
seeding	(only valid for bt) download is over, the content is Change to being shared to other users. The task will automatically stop once the seed ratio has been reached
retry	You can set a task status to ‘retry’ to restart the download task.

size int Read-only¶: download size (in Bytes)

queue_pos int¶: position in download queue (0 if not queued)

io_priority enum¶

The valid download priorities are:

Priority	Description
low	low
normal	normal
high	high

tx_bytes int Read-only¶: transmitted bytes (including protocol overhead)

rx_bytes int Read-only¶: received bytes (including protocol overhead)

tx_rate int Read-only¶: current transmit rate (in byte/s)

rx_rate int Read-only¶: current receive rate (in byte/s)

tx_pct int Read-only¶

transmit percentage (without protocol overhead)

To improve precision the value as been scaled by 100 so that a tx_pct of 123 means 1.23%

rx_pct int Read-only¶

received percentage (without protocol overhead)

To improve precision the value as been scaled by 100 so that a tx_pct of 123 means 1.23%

error enum Read-only¶: An error code

created_ts timestamp Read-only¶: timestamp of the download creation time

eta int Read-only¶: estimated remaining download time (in seconds)

download_dir string Read-only¶: directory where the file(s) will be saved (base64 encoded)

stop_ratio int Read-only¶

Only relevant for bittorrent tasks. Once the transmit ration has been reached the task will stop seeding.

The ratio is scaled by 100 to improve resolution.

A stop_ratio of 150 means that the task will stop seeding once tx_bytes = 1.5 * rx_bytes.

archive_password string¶: (only relevant for nzb) password for extracting downloaded archives

info_hash string¶: (only relevant for bt) torrent info_hash encoded in hexa

piece_length int¶: (only relevant for bt) torrent piece length in bytes

Download API¶

Retrieve a Download task¶

GET /api/v4/downloads/¶

Returns the collection of all Download tasks

Example request:

GET /api/v4/downloads/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
      "success": true,
      "result": {
            "rx_bytes": 147450,
            "tx_bytes": 3460,
            "download_dir": "L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMv",
            "archive_password": "",
            "eta": 60290,
            "status": "downloading",
            "io_priority": "normal",
            "type": "bt",
            "piece_length": 524288,
            "queue_pos": 2,
            "id": 1273,
            "info_hash": "A7055D06E5A8F7F816EC01AC7F7F5243D3CB008F",
            "created_ts": 1485513882,
            "stop_ratio": 150,
            "tx_rate": 202,
            "name": "debian-8.7.1-amd64-CD-1.iso",
            "tx_pct": 0,
            "rx_pct": 0,
            "rx_rate": 10950,
            "error": "none",
            "size": 660600000
      }
}

GET /api/v4/downloads/{id}¶

Returns the Download task with the given id

Example request:

GET /api/v4/downloads/16 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "rx_bytes": 688005364,
        "tx_bytes": 3232055279,
        "download_dir": "L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMv", /* /Disque dur/Téléchargements/ */
        "archive_password": "",
        "eta": 331896,
        "status": "seeding",
        "io_priority": "high",
        "size": 678428672,
        "type": "bt",
        "error": "none",
        "queue_pos": 0,
        "id": 14,
        "created_ts": 1349786169,
        "tx_rate": 0,
        "name": "debian-6.0.6-amd64-CD-1.iso",
        "rx_pct": 10000,
        "rx_rate": 0,
        "tx_pct": 0
    }

}

Delete a Download task¶

DELETE /api/v4/downloads/{id}¶

Deletes the Download task with the given id, without erasing the downloaded files If the task was not done it is stopped

You can call this method to remove done tasks from the task list.

Example request:

DELETE /api/v4/downloads/16 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true
}

DELETE /api/v4/downloads/{id}/erase¶: Same as previous, but erases the downloaded files

Update a Download task¶

PUT /api/v4/downloads/{id}¶

Updates the Download task with the given id

Example request:

PUT /api/v4/downloads/16 HTTP/1.1
Host: mafreebox.freebox.fr

{
   "io_priority": "high",
   "status": "stopped"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": {
        "rx_bytes": 683407058,
        "tx_bytes": 17866436,
        "download_dir": "L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMv", /* /Disque dur/Téléchargements/ */
        "eta": 1075260392,
        "status": "stopping",
        "io_priority": "high",
        "size": 678428672,
        "type": "bt",
        "error": "none",
        "queue_pos": 0,
        "id": 14,
        "created_ts": 1349786169,
        "tx_rate": 0,
        "name": "debian-6.0.6-amd64-CD-1.iso",
        "stop_ratio": 55936,
        "rx_pct": 10000,
        "rx_rate": 0,
        "tx_pct": 4
    }
}

Get download log¶

GET /api/v4/downloads/{id}/log¶

Get the log.

Example request:

GET /api/v4/downloads/16/log HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "success": true,
    "result": "log line\nanother log line\n"
}

Adding a new Download task¶

Adding by URL¶

Supported URL scheme are http://, ftp://, magnet:

You can start a recursive download by setting the recursive parameter. The downloader will then extract links from each donwloaded html page and continue downloading files on the same domain and on the same root path. This can be used to download all the files on a directory index.

You can add multiple downloads at once by passing a list of URL (separated by a new line delimiter) in download_url_list instead of using download_url.

/!NOTE: for this API the request arguments must be encoded using “application/x-www-form-urlencoded” (or “multipart/form-data” for file upload) instead of “application/json”

POST /api/v4/downloads/add¶

Parameters:

Parameters:	download_url (string) – The URL download_url_list (string) – A list of URL separated by a new line delimiter (use download_url or download_url_list) download_dir (string) – The download destination directory (optional: will use the configuration download_dir by default) recursive (bool) – If true the download will be recursive username (string) – Auth username (optional) password (string) – Auth password (optional) archive_password (string) – The password required to extract downloaded content (only relevant for nzb) cookies (string) – The http cookies (to be able to pass session cookies along with url)

download_url (string) – The URL
download_url_list (string) – A list of URL separated by a new line delimiter (use download_url or download_url_list)
download_dir (string) – The download destination directory (optional: will use the configuration download_dir by default)
recursive (bool) – If true the download will be recursive
username (string) – Auth username (optional)
password (string) – Auth password (optional)
archive_password (string) – The password required to extract downloaded content (only relevant for nzb)
cookies (string) – The http cookies (to be able to pass session cookies along with url)

NOTE: instead of passing password and username you can include them in the URL.

Example request : Single download add:

POST /api/v4/downloads/add HTTP/1.1
Host: mafreebox.freebox.fr

download_url=http%3A%2F%2Fcdimage.debian.org%2Fdebian-cd%2F6.0.6%2Famd64%2Fbt-cd%2Fdebian-6.0.6-amd64-CD-1.iso.torrent
&download_dir=L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMv

Example response:

On success you’ll get the id of the new download task.

{
   "result": {
      "id": 23
    },
   "success": true
}

Example request : Multiple downloads at once:

POST /api/v4/downloads/add HTTP/1.1
Host: mafreebox.freebox.fr

download_url_list=ftp%3A%2F%2Ftest-debit.free.fr%2F1024.rnd
         %0Ahttp%3A%2F%2Ftest-debit.free.fr%2F4096.rnd
         %0Ahttp%3A%2F%2Ftest-debit.free.fr%2F32768.rnd
&download_dir=L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMv

Example response:

On success you’ll get the list of id of the new download tasks.

{
   "result": {
       "id": [
           32,
           33,
           34
       ]
    },
    "success": true
}

Adding by file upload¶

Supported files are .torrent, .nzb,

POST /api/v4/downloads/add¶

Parameters:	download_file (string) – The download file (must be uploaded using multipart/form-data download_dir (string) – The download destination directory (optional: will use the configuration download_dir by default) archive_password (string) – The password required to extract downloaded content (only relevant for nzb)

Example request:

POST /api/v4/downloads/add HTTP/1.1
Host: mafreebox.freebox.fr
Content-Type: multipart/form-data; boundary=---------------------------176791920111939857911845395343
Content-Length: 26651

-----------------------------176791920111939857911845395343
Content-Disposition: form-data; name="download_dir"

L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMv
-----------------------------176791920111939857911845395343
Content-Disposition: form-data; name="archive_password"


-----------------------------176791920111939857911845395343
Content-Disposition: form-data; name="download_file"; filename="debian-6.0.6-amd64-CD-1.iso.torrent"
Content-Type: application/x-bittorrent

d8:announce41:http://bttracker.debian.org:6969/announce7:comment [ ... ]

Example response:

{
   "result": {
      "id": 42
   },
   "success": true
}

Download Stats¶

If you just want to display synthetic information about downloader this is the method to use.

Download Nzb configuration status Object¶

NzbConfigStatus¶

status enum Read-only¶

The valid config status are:

Type	Description
not_checked	config has not been checked yet
checking	test in progress
error	config is invalid, see error
ok	config is ok

error enum Read-only¶

The valid config status are:

Type	Description
none	test is ok
nzb_authentication_required	authentication is required
bad_authentication	incorrect credentials
connection_refused	unable to connect to NNTP server

Download DHT stats Object¶

DhtStats¶

enabled bool Read-only¶: is the dht enabled

node_count int Read-only¶: number of active nodes

enabled_ipv6 bool Read-only¶: is the dht enabled on IPv6

node_count_ipv6 int Read-only¶: number of active nodes on IPv6

Download Stats Object¶

DownloadStats¶

nb_tasks int Read-only¶: total number of tasks

nb_tasks_stopped int Read-only¶: number of stopped tasks

nb_tasks_checking int Read-only¶: number of checking tasks

nb_tasks_queued int Read-only¶: number of queued tasks

nb_tasks_extracting int Read-only¶: number of extracting tasks

nb_tasks_done int Read-only¶: number of done tasks

nb_tasks_repairing int Read-only¶: number of repairing tasks

nb_tasks_seeding int Read-only¶: number of seeding tasks

nb_tasks_downloading int Read-only¶: number of downloading tasks

nb_tasks_error int Read-only¶: number of error tasks

nb_tasks_stopping int Read-only¶: number of stopping tasks

nb_tasks_active int Read-only¶: number of active tasks (checking + queued + extracting + repairing + seeding + downloading)

nb_rss int Read-only¶: number of RSS feed subscriptions

nb_rss_items_unread int Read-only¶: number of unread RSS items

rx_rate int Read-only¶: current receive rate in bytes / second

tx_rate int Read-only¶: current transmit rate in bytes / second

throttling_mode enum Read-only¶: active throttling_mode (see DlThrottlingConfig)

throttling_is_scheduled bool Read-only¶

if true, the current throttling mode has been computed using the throttling schedule

if false, the current throttling mode has been manually forced

throttling_rate :json:object:`DlRate` Read-only¶: current rate for throttling

nzb_config_status :json:object:`NzbConfigStatus` Read-only¶: current nzb configuration status

conn_ready bool Read-only¶: is the connection ready

nb_peer int Read-only¶: number of bittorrent peers

blocklist_entries int Read-only¶: number of rules in blocklist

blocklist_hits int Read-only¶: number of hits in blocklist

dht_stats :json:object:`DhtStats` Read-only¶: dht stats

Get the Download Stats¶

GET /api/v4/downloads/stats¶

Example request:

GET /api/v4/downloads/stats HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
    "success": true,
    "result": {
        "throttling_rate": {
            "rx_rate": 0,
            "tx_rate": 0
        },
        "nb_tasks_stopped": 1,
        "nb_tasks_checking": 0,
        "nb_tasks_queued": 0,
        "nb_tasks_extracting": 4,
        "nb_tasks_done": 1,
        "nb_tasks_repairing": 0,
        "throttling_mode": "normal",
        "nb_tasks_active": 11,
        "tx_rate": 4294,
        "nb_tasks_downloading": 4,
        "throttling_is_scheduled": true,
        "nb_tasks": 13,
        "nb_tasks_error": 0,
        "nb_tasks_stopping": 0,
        "nb_rss_items_unread": 5,
        "rx_rate": 14222,
        "nb_tasks_seeding": 3
    }
}

Download Files¶

Download Files Object¶

Each Download has one or more DownloadFile.

DownloadFile¶

id string Read-only¶: opaque id

task_id int Read-only¶: id of the download task

path string Read-only¶: [ DEPRECATED ]

filepath string Read-only¶: full filepath on the disk (encoded as in file system api)

name string Read-only¶: file name

mimetype string Read-only¶: file mimetype

size int Read-only¶: file size in bytes

rx int Read-only¶: received bytes

status enum Read-only¶

file download status

Status	Description
queued	file is queued for download
error	there was a problem with this file, see error to get the error code
done	file download is completed

error enum Read-only¶: file error code in case status is error

priority string¶

file download priority inside the download task

Priority	Description
no_dl	this file will not be downloaded
low	low priority
normal	default priority
high	high priority

preview_url string Read-only¶: url to preview downloaded file (only available for bittorrent) as a share link, this url can be use without requiring any form of authentication so that it can be passed as-is to any software.

Download Files API¶

Get the list of files for a given Download¶

GET /api/v4/downloads/{task_id}/files¶

Example request:

GET /api/v4/downloads/37/files HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
    "success": true,
    "result": [
      {
          "path": "/Disque dur/Téléchargements//test-debit.free.fr.html",
          "id": "5-1",
          "task_id": "5",
          "filepath": "L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMvL3Rlc3QtZGViaXQuZnJlZS5mci5odG1s",
          "mimetype": "text/html",
          "name": "test-debit.free.fr.html",
          "rx": 0,
          "status": "done",
          "priority": "normal",
          "error": "none",
          "size": 0

      },
      {
          "path": "/Disque dur/Téléchargements//test-debit.free.fr/1024.rnd",
          "id": "5-7",
          "task_id": "5",
          "filepath": "L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMvL3Rlc3QtZGViaXQuZnJlZS5mci8xMDI0LnJuZA==",
          "mimetype": "application/octet-stream",
          "name": "1024.rnd",
          "rx": 1048576,
          "status": "done",
          "priority": "low",
          "error": "none",
          "size": 1048576
      },

        [ ... ]

      {
          "path": "/Disque dur/Téléchargements//test-debit.free.fr/image.iso",
          "id": "5-16",
          "task_id": "5",
          "filepath": "L0Rpc3F1ZSBkdXIvVMOpbMOpY2hhcmdlbWVudHMvL3Rlc3QtZGViaXQuZnJlZS5mci9pbWFnZS5pc28=",
          "mimetype": "application/x-cd-image",
          "name": "image.iso",
          "rx": 678428672,
          "status": "done",
          "priority": "low",
          "error": "none",
          "size": 678428672
      }
    ]

}

Change the priority of a Download File¶

PUT /api/v4/downloads/{task_id}/files/{file_id}¶

Parameters:	task_id (string) – The download task id path (string) – The file_id priority (string) – The new file download priority

Example request:

PUT /api/v4/downloads/37/files/37-4 HTTP/1.1
Host: mafreebox.freebox.fr

{
  "priority" : "high"
}

Example response:

{
   "success": true
}

Download Trackers [UNSTABLE]¶

Download Tracker Object¶

Each torrent Download task has one or more DownloadTracker.

Each tracker is identified by its announce URL.

DownloadTracker¶

announce string Read-only¶: tracker announce URL

is_backup bool Read-only¶: true if the tracker is a backup tracker (the downloader won’t connect to this tracker unless the primary tracker fails)

status enum Read-only¶

tracker status

Status	Description
unannounced	not announced
announcing	announcing
announce_failed	an error occurred while trying to announce
announced	announced

interval int Read-only¶: desired interval between two announces (in seconds)

min_interval int Read-only¶: minimum interval between two announces (in seconds)

reannounce_in int Read-only¶: time left before reannounce (in seconds)

nseeders int Read-only¶: number of seeders announced on tracker

nleechers int Read-only¶: number of leechers announced on tracker

is_enabled bool¶: is the tracker enabled

Download Tracker API¶

Get the list of trackers for a given Download¶

Attempting to call this method on a download other than bittorent will fail

GET /api/v4/downloads/{task_id}/trackers¶

Example request:

GET /api/v4/downloads/35/tracker HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
    "success": true,
    "result": [
        {
            "nseeders": 0,
            "nleechers": 0,
            "reannounce_in": 790,
            "is_backup": false,
            "interval": 900,
            "min_interval": 60,
            "announce": "http://bttracker.debian.org:6969/announce",
            "status": "announced"
        }
    ]
}

Add a new tracker¶

Attempting to call this method on a download other than bittorent will fail

POST /api/v4/downloads/{task_id}/trackers¶

Example request:

POST /api/v4/downloads/35/tracker HTTP/1.1
Host: mafreebox.freebox.fr

{
  "announce": "udp://tracker.openbittorrent.com:80"
}

Example response:

{
    "success": true
}

Remove a tracker¶

DELETE /api/v4/downloads/{task_id}/trackers/{announce}¶

Example request:

DELETE /api/v4/downloads/35/tracker/udp%3A%2F%2Ftracker.openbittorrent.com%3A80 HTTP/1.1
Host: mafreebox.freebox.fr

{
  "announce": "udp://tracker.openbittorrent.com:80"
}

Example response:

{
    "success": true
}

Update a tracker¶

PUT /api/v4/downloads/{task_id}/trackers/{announce}¶

Example request:

PUT /api/v4/downloads/35/tracker/udp%3A%2F%2Ftracker.openbittorrent.com%3A80 HTTP/1.1
Host: mafreebox.freebox.fr

{
  "announce": "udp://tracker.openbittorrent.com:80",
  "is_enabled": true
}

Example response:

{
    "success": true
}

Download Peers [UNSTABLE]¶

Download Peer Object¶

Each torrent Download task has one or more DownloadPeer.

DownloadPeer¶

host string Read-only¶: peer IP

port int Read-only¶: peer port

state enum Read-only¶

peer state

State	Description
disconnected	not connected
connecting	trying to connect to the peer
handshaking	connected to the peer, negotiating capabilities
ready	ready to exchange data

origin enum Read-only¶

peer origin

Origin	Description
tracker	got the peer from the tracker
incoming	incoming peer
dht	got the peer from DHT
pex	got the peer from Peer exchange protocol
user	manually added peer

protocol enum Read-only¶

Protocol	Description
tcp	TCP
tcp_obfuscated	Obfuscated TCP
udp	UDP

client string Read-only¶: Bittorrent client name

country_code string Read-only¶

Peer country code (iso 3166)

If country code is not available it will have the value ”??”

tx int Read-only¶: transmitted bytes

rx int Read-only¶: received bytes

tx_rate int Read-only¶: current transmit rate in byte/s

rx_rate int Read-only¶: current receive rate in byte/s

progress int Read-only¶: peer current download progress

requests[] array of int Read-only¶: current requested pieces

Get the list of peers for a given Download¶

Attempting to call this method on a download other than bittorent will fail

GET /api/v4/downloads/{task_id}/peers¶

Example request:

GET /api/v4/downloads/42/peers HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
    "success": true,
    "result": [
        {
            "protocol": "tcp_obfuscated",
            "origin": "tracker",
            "progress": 91,
            "remote_choke": true,
            "requests": { },
            "host": "186.213.200.201",
            "port": 0,
            "client": "Azureus 4.7.2.0",
            "country_code": "BR",
            "local_interest": false,
            "state": "ready",
            "rx": 1617,
            "tx": 836670,
            "remote_interest": true,
            "tx_rate": 0,
            "rx_rate": 0,
            "local_choke": false
        },

        [ ... ]

        {
          "protocol": "tcp",
          "origin": "tracker",
          "progress": 11,
          "remote_choke": true,
          "requests": { },
          "host": "208.127.4.60",
          "port": 0,
          "client": "Transmission 2.51",
          "country_code": "US",
          "local_interest": false,
          "state": "ready",
          "rx": 8929,
          "tx": 7592234,
          "remote_interest": true,
          "tx_rate": 0,
          "rx_rate": 0,
          "local_choke": false
        }
    ]

}

Download Pieces¶

Each Torrent is split in ‘pieces’ of fixed size. The Download Piece Api allow tracking the download state of each pieces of a Torrent

Get the pieces status a given download¶

The result value is a string, with each character representing a piece status. Piece status can be:

Status Description

X piece is complete

piece is currently downloading

. piece is wanted but not downloading yet

piece is not wanted and will not be downloaded

/ piece is downloading with high priority as it is needed for file preview

U piece is scheduled with high priority as it is needed for file preview

Status	Description
X	piece is complete
	piece is currently downloading
.	piece is wanted but not downloading yet
	piece is not wanted and will not be downloaded
/	piece is downloading with high priority as it is needed for file preview
U	piece is scheduled with high priority as it is needed for file preview

GET /api/v4/downloads/{task_id}/pieces¶

Example request:

GET /api/v4/api/v1/downloads/5/pieces HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
    "success": true,
    "result": "XXXXX//++....-- [ ... ] XXX"
}

Download Blacklist [UNSTABLE]¶

For bittorrent downloads, we use a blacklist to store information about “useless” or broken peers. For instance if a peer is complete and we are trying to seed data, there is no use attempting to connect to this peer again.

The download blacklist api allow you to retreive information about this blacklist, and remove, or add peers to the blacklist.

Each DownloadBlacklistEntry can be specific to a torrent, or “global” and apply to any torrent.

Download Blacklist Object¶

DownloadBlacklistEntry¶

host string Read-only¶: entry ip

reason enum Read-only¶

blacklist reason

State	Description
disconnected	not connected
connecting	trying to connect to the peer
handshaking	connected to the peer, negotiating capabilities
ready	ready to exchange data

expire int Read-only¶: time left before blacklist removal

global bool Read-only¶: does this entry applies to all torrents

Get the list of blacklist entries for a given download¶

Attempting to call this method on a download other than bittorent will fail.

GET /api/v4/downloads/{task_id}/blacklist¶

Example request:

GET /api/v4/api/v1/downloads/5/blacklist HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
    "success": true,
    "result": [
        {
            "host": "89.215.188.6",
            "expire": 90,
            "global": true,
            "reason": "torrent_not_found"
        },
        {
            "host": "94.23.0.89",
            "expire": 120,
            "global": true,
            "reason": "conn_closed"
        },
        {
            "host": "188.254.151.215",
            "expire": 150,
            "global": true,
            "reason": "timeout"
        },
        {
            "host": "201.25.54.26",
            "expire": 180,
            "global": true,
            "reason": "timeout"
        }
    ]
}

Empty the blacklist for a given download¶

This call allow to remove all global entries, and entries related to the given download

DELETE /api/v4/downloads/{task_id}/blacklist/empty¶

Example request:

DELETE /api/v4/api/v1/downloads/5/blacklist/empty HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
   "success": true
}

Delete a particular blacklist entry¶

DELETE /api/v4/downloads/blacklist/{host}¶

Example request:

DELETE /api/v4/api/v1/downloads/blacklist/201.25.54.26 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

{
   "success": true
}

Add a blacklist entry¶

POST /api/v4/downloads/blacklist¶

Example request:

POST /api/v4/downloads/blacklist HTTP/1.1
Host: mafreebox.freebox.fr

{
  "host": "8.8.8.8",
  "expire": 3600
}

Example response:

{
    "success": true,
    "result":
       {
          "host": "197.200.139.87",
          "expire": 300,
          "global": true,
          "reason": "user"
       }
}