BitTorrent Sync API Beta

The BitTorrent Sync API offers developers a wide range of of possibilities. You can integrate Sync into your own apps, build, improve, and change the way Sync works on your devices, or use the API to automate workflows. We’re excited to share Sync, and we’re happy to have you on board. Welcome to Sync!

How do I get a key?

In order to use the BitTorrent Sync API, you'll need a special API key. Fill out this short form to get your key. Make sure to include a valid email address and accept the terms and conditions of using the API. You’ll then receive an email with all of the info you need to start coding.

API exclusive features


Encryption secret
API users can generate folder secrets with encrypted peer support. Encryption secrets are read-only. They make Sync data encrypted on the receiver’s side. Recipients can sync files, but they can’t see file content, and they can’t modify the files. Encryption secrets come in handy if you need to sync to an untrusted location.

Selective sync
The API allows you to set a selective_sync parameter and specify a sync mode. If set to "selective", the client will only sync the files marked for download through the 'Set file preferences' function. Otherwise, all the files in the folder will be synced.

Enabling the API


To enable the API, you must run BitTorrent Sync with the config file. All official BitTorrent Sync clients will support the API. By using the config file, you will have the ability to run Sync silently without installation, allowing improved integration with your app.

On Mac and Linux, run the Sync executable with --config path_to_file argument.
On Windows, use /config path_to_file.
The config file may be located in any directory on your drive.

Sync uses JSON format for the configuration file. Here is a sample config file that you can use to enable API:

{
    // path to folder where Sync will store its internal data,
    // folder must exist on disk
    "storage_path" : "/Users/user/.SyncAPI",

    // run Sync in GUI-less mode
    "use_gui" : false,

    "webui" : {
        // IP address and port to access HTTP API
        "listen" : "127.0.0.1:8888",
        // login and password for HTTP basic authentication
        // authentication is optional, but it's recommended to use some
        // secret values unique for each Sync installation
        "login" : "api",
        "password" : "secret",
        // replace xxx with API key received from BitTorrent
        "api_key" : "xxx"
    }
}

It is important to note that you should create your own login and password for security reasons to replace the default settings above.

API Functions

Get folders

Returns an array with folders info. If a secret is specified, will return info about the folder with this secret.

[
    {
        "dir": "\\\\?\\D:\\share",
        "secret": "A54HDDMPN4T4BTBT7SPBWXDB7JVYZ2K6D",
        "size": 23762511569,
        "type": "read_write",
        "files": 3206,
        "error": 0,
        "indexing": 0
    }
]

http://[address]:[port]/api?method=get_folders[&secret=(secret)]

  • secret (optional) - if a secret is specified, will return info about the folder with this secret

Add folder

Adds a folder to Sync. If a secret is not specified, it will be generated automatically. The folder will have to pre-exist on the disk and Sync will add it into a list of syncing folders.
Returns '0' if no errors, error code and error message otherwise.

{ "error": 0 }

http://[address]:[port]/api?method=add_folder&dir=(folderPath)[&secret=(secret)&selective_sync=1]

  • dir (required) - specify path to the sync folder
  • secret (optional) - specify folder secret
  • selective_sync (optional) - specify sync mode, selective - 1, all files (default) - 0

Remove folder

Removes folder from Sync while leaving actual folder and files on disk. It will remove a folder from the Sync list of folders and does not touch any files or folders on disk. Returns '0' if no error, '1' if there’s no folder with specified secret.

{ "error": 0 }

http://[address]:[port]/api?method=remove_folder&secret=(secret)

  • secret (required) - specify folder secret

Get files

Returns list of files within the specified directory. If a directory is not specified, will return list of files and folders within the root folder. Note that the Selective Sync function is only available in the API at this time.

[
    {
        "name": "images",
        "state": "created",
        "type": "folder"
    },
    {
        "have_pieces": 1,
        "name": "index.html",
        "size": 2726,
        "state": "created",
        "total_pieces": 1,
        "type": "file",
        "download": 1 // only for selective sync folders
    }
]

http://[address]:[port]/api?method=get_files&secret=(secret)[&path=(path)]

  • secret (required) - must specify folder secret
  • path (optional) - specify path to a subfolder of the sync folder.

Set file preferences

Selects file for download for selective sync folders. Returns file information with applied preferences.

http://[address]:[port]/api?method=set_file_prefs&secret=(secret)&path=(path)&download=1

  • secret (required) - must specify folder secret
  • path (required) - specify path to a subfolder of the sync folder.
  • download (required) - specify if file should be downloaded (yes - 1, no - 0)

Get folder peers

Returns list of peers connected to the specified folder.

[
    {
        "id": "ARRdk5XANMb7RmQqEDfEZE-k5aI=",
        "connection": "direct", // direct or relay
        "name": "GT-I9500",
        "synced": 0, // timestamp when last sync completed
        "download": 0,
        "upload": 22455367417
    }
]

http://[address]:[port]/api?method=get_folder_peers&secret=(secret)

  • secret (required) - must specify folder secret

Get secrets

Generates read-write, read-only and encryption read-only secrets. If ‘secret’ parameter is specified, will return secrets available for sharing under this secret.
The Encryption Secret is new functionality. This is a secret for a read-only peer with encrypted content (the peer can sync files but can not see their content). One example use is if a user wanted to backup files to an untrusted, unsecure, or public location. This is set to disabled by default for all users but included in the API.

{
    "read_only": "ECK2S6MDDD7EOKKJZOQNOWDTJBEEUKGME",
    "read_write": "DPFABC4IZX33WBDRXRPPCVYA353WSC3Q6",
    "encryption": "G3PNU7KTYM63VNQZFPP3Q3GAMTPRWDEZ”
}

http://[address]:[port]/api?method=get_secrets[&secret=(secret)&type=encryption]

  • secret (required) - must specify folder secret
  • type (optional) - if type=encrypted, generate secret with support of encrypted peer

Get folder preferences

Returns preferences for the specified sync folder.

{
    "search_lan":1,
    "use_dht":0,
    "use_hosts":0,
    "use_relay_server":1,
    "use_sync_trash":1,
    "use_tracker":1
}

http://[address]:[port]/api?method=get_folder_prefs&secret(secret)

  • secret (required) - must specify folder secret

Set folder preferences

Sets preferences for the specified sync folder. Parameters are the same as in ‘Get folder preferences’. Returns current settings.

http://[address]:[port]/api?method=set_folder_prefs&secret=(secret)&param1=value1&param2=value2,...

  • secret (required) - must specify folder secret
  • params - { use_dht, use_hosts, search_lan, use_relay_server, use_tracker, use_sync_trash }

Get folder hosts

Returns list of predefined hosts for the folder, or error code if a secret is not specified.

{
    "hosts" : ["192.168.1.1:4567",
    "example.com:8975"]
}

http://[address]:[port]/api?method=get_folder_hosts&secret=(secret)

  • secret (required) - must specify folder secret

Set folder hosts

Sets one or several predefined hosts for the specified sync folder. Existing list of hosts will be replaced. Hosts should be added as values of the ‘host’ parameter and separated by commas. Returns current hosts if set successfully, error code otherwise.

http://[address]:[port]/api?method=set_folder_hosts&secret=(secret)&hosts=host1:port1,host2:port2,...

  • secret (required) - must specify folder secret
  • hosts (required) - enter list of hosts separated by comma. Host should be represented as “[address]:[port]”

Get preferences

Returns BitTorrent Sync preferences. Contains dictionary with advanced preferences. Please see Sync user guide for description of each option.

{
    "device_name" : "iMac",
    "disk_low_priority": "true",
    "download_limit": 0,
    "folder_rescan_interval": "600",
    "lan_encrypt_data": "true",
    "lan_use_tcp": "false",
    "lang": -1,
    "listening_port": 11589,
    "max_file_size_diff_for_patching": "1000",
    "max_file_size_for_versioning": "1000",
    "rate_limit_local_peers": "false",
    "send_buf_size": "5",
    "sync_max_time_diff": "600",
    "sync_trash_ttl": "30",
    "upload_limit": 0,
    "use_upnp": 0,
    "recv_buf_size": "5"
}

http://[address]:[port]/api?method=get_prefs

Set preferences

Sets BitTorrent Sync preferences. Parameters are the same as in ‘Get preferences’. Advanced preferences are set as general settings. Returns current settings.

http://[address]:[port]/api?method=set_prefs&param1=value1&param2=value2,...

  • params - { device_name, download_limit, lang, listening_port, upload_limit, use_upnp } and advanced settings. You can find more information about advanced settings in user guide.

Get OS name

Returns OS name where BitTorrent Sync is running.

{ "os": "win32" }

http://[address]:[port]/api?method=get_os

Get version

Returns BitTorrent Sync version.

{ "version": "1.2.48" }

http://[address]:[port]/api?method=get_version

Get speed

Returns current upload and download speed.

{
    "download": 61007,
    "upload": 0
}

http://[address]:[port]/api?method=get_speed

Shutdown

Gracefully stops Sync.

{ "error" : 0 }

http://[address]:[port]/api?method=shutdown