BitDust API


Stop the main process immediately.

{'status': 'OK', 'result': 'stopped'}


Restart the main process, if flag show=True the GUI will be opened after restart.

{'status': 'OK', 'result': 'restarted'}


Deprecated. Opens a default web browser to show the BitDust GUI.

{'status': 'OK',   'result': '"show" event has been sent to the main process'}


Returns true if system is running

{'status': 'OK' }


Execute a breakpoint inside main thread and start Python shell using standard pdb.set_trace() debugger.


Returns current value for specific option from program settings.

{'status': 'OK',   'result': [{'type': 'positive integer', 'value': '8', 'key': 'logs/debug-level'}]}

config_set(key, value)

Set a value for given option.

{'status': 'OK', 'result': [{'type': 'positive integer', 'old_value': '8', 'value': '10', 'key': 'logs/debug-level'}]}


Provide detailed info about all options and values from settings.

{'status': 'OK',
 'result': [{
    'type': 'boolean',
    'value': 'true',
    'key': 'services/backups/enabled'
 }, {
    'type': 'boolean',
    'value': 'false',
    'key': 'services/backups/keep-local-copies-enabled'
 }, {
    'type': 'diskspace',
    'value': '128 MB',
    'key': 'services/backups/max-block-size'


Returns all options as a tree.


identity_create(username, preferred_servers=[])


identity_recover(private_key_source, known_idurl=None)



key_get(key_id, include_private=False)

Returns details of known private key. Use include_private=True to get Private Key as openssh formated string.

{'status': 'OK'.
 'result': [{
    'alias': 'cool',
    'creator': '',
    'key_id': 'cool$',
    'fingerprint': '50:f9:f1:6d:e3:e4:25:61:0c:81:6f:79:24:4e:78:17',
    'size': '4096',
    'ssh_type': 'ssh-rsa',
    'type': 'RSA',
    'public': 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCPy7AXI0HuQSdmMF...',
    'private': '-----BEGIN RSA PRIVATE KEY-----\nMIIJKAIBAAKCAgEAj8uw...'

keys_list(sort=False, include_private=False)

List details for known Private Keys. Use include_private=True to get Private Keys as openssh formated strings.

{'status': 'OK',
 'result': [{
     'alias': 'master',
     'key_id': 'master$',
     'creator': '',
     'fingerprint': '60:ce:ea:98:bf:3d:aa:ba:29:1e:b9:0c:3e:5c:3e:32',
     'size': '2048',
     'ssh_type': 'ssh-rsa',
     'type': 'RSA',
     'public': 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDbpo3VYR5zvLe5...'
     'private': '-----BEGIN RSA PRIVATE KEY-----\nMIIJKAIBAAKCAgEAj8uw...'
 }, {
     'alias': 'another_key01',
     'label': 'ABC',
     'key_id': 'another_key01$',
     'creator': '',
     'fingerprint': '43:c8:3b:b6:da:3e:8a:3c:48:6f:92:bb:74:b4:05:6b',
     'size': '4096',
     'ssh_type': 'ssh-rsa',
     'type': 'RSA',
     'public': 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCmgX6j2MwEyY...'
     'private': '-----BEGIN RSA PRIVATE KEY-----\nMIIJKsdAIBSjfAdfguw...'

key_create(key_alias, key_size=None, label='', include_private=False)

Generate new Private Key and add it to the list of known keys with given key_id.

{'status': 'OK',
 'message': 'new private key "abcd" was generated successfully',
 'result': [{
    'alias': 'abcd',
    'id': 'abcd$',
    'creator': '',
    'fingerprint': 'bb:16:97:65:59:23:c2:5d:62:9d:ce:7d:36:73:c6:1f',
    'size': '4096',
    'ssh_type': 'ssh-rsa',
    'type': 'RSA',
    'public': 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC8w2MhOPR/IoQ...'
    'private': '-----BEGIN RSA PRIVATE KEY-----\nMIIJKsdAIBSjfAdfguw...'

key_label(key_id, label)

Set new label for given key.


Removes Private Key from the list of known keys and erase local file.

{'status': 'OK',
 'message': 'private key "abcd$" was erased successfully',

key_share(key_id, trusted_global_id_or_idurl, include_private=False, timeout=10)

Connects to remote node and transfer private key to that machine. This way remote user will be able to access those of your files which were encrypted with that private key. You can also share a public key, this way your supplier will know which data packets can be accessed by another customer.


key_audit(key_id, untrusted_global_id_or_idurl, is_private=False, timeout=10)

Connects to remote node identified by idurl parameter and request audit of a public or private key key_id on that machine. Returns True in the callback if audit process succeed - that means remote user posses that public or private key.



A service method to execute calls from GUI front-end and interact with web browser. This is a special "gates" created only for Ajax calls from GUI. It provides same methods as other functions here, but just in a different way.


    {'bytes_donated': 8589934592,
     'bytes_indexed': 43349475,
     'bytes_needed': 104857600,
     'bytes_used_supplier': 21738768,
     'bytes_used_total': 86955072,
     'customers': 0,
     'files_count': 5,
     'folders_count': 0,
     'items_count': 15,
     'max_suppliers': 4,
     'online_suppliers': 0,
     'suppliers': 4,
     'timestamp': 1458669668.288339,
     'value_donated': '8 GB',
     'value_needed': '100 MB',
     'value_used_total': '82.93 MB'}

You can also access those methods with another API "alias": filemanager_{ mode }({ extra params })

WARNING: Those methods here will be deprecated and removed, use regular API methods instead.


Sends "restart" event to backup_monitor() Automat, this should start "data synchronization" process with remote nodes. Normally all situations should be handled automatically so you wont run this method manually, but just in case.

{'status': 'OK', 'result': 'the main files sync loop has been restarted'}


file_info(remote_path, include_uploads=True, include_downloads=True)

file_create(remote_path, as_folder=False)


files_uploads(include_running=True, include_pending=True)

Returns a list of currently running uploads and list of pending items to be uploaded.

{ 'status': 'OK',
  'result': {
    'running': [{
        'aborting': False,
        'version': '0/0/3/1/F20160424013912PM',
        'block_number': 4,
        'block_size': 16777216,
        'bytes_processed': 67108864,
        'closed': False,
        'eccmap': 'ecc/4x4',
        'eof_state': False,
        'pipe': 0,
        'progress': 75.0142815704418,
        'reading': False,
        'source_path': '/Users/veselin/Downloads/',
        'terminating': False,
        'total_size': 89461450,
        'work_blocks': 4
    'pending': [{
        'created': 'Wed Apr 27 15:11:13 2016',
        'id': 3,
        'source_path': '/Users/veselin/Downloads/',
        'path_id': '0/0/3/2'

file_upload_start(local_path, remote_path, wait_result=False, open_share=False)



Returns a list of currently running downloads.

{'status': 'OK',
 'result': [{
    'aborted': False,
    'backup_id': '0/0/3/1/F20160427011209PM',
    'block_number': 0,
    'bytes_processed': 0,
    'creator_id': '',
    'done': False,
    'key_id': 'abc$',
    'created': 'Wed Apr 27 15:11:13 2016',
    'eccmap': 'ecc/4x4',
    'path_id': '0/0/3/1',
    'version': 'F20160427011209PM'

file_download_start(remote_path, destination_path=None, wait_result=False, open_share=True)

Download data from remote suppliers to your local machine. You can use different methods to select the target data with remote_path input:

  • "remote path" of the file
  • item ID in the catalog
  • full version identifier with item ID

It is possible to select the destination folder to extract requested files to. By default this method uses specified value from local settings or user home folder

WARNING: Your existing local data will be overwritten!

{'status': 'OK', 'result': 'downloading of version 0/0/1/1/0/F20160313043419PM has been started to /Users/veselin/'}


Abort currently running restore process.

{'status': 'OK', 'result': 'restoring of "" aborted'}


share_list(only_active=False, include_mine=True, include_granted=True)

share_create(owner_id=None, key_size=2048, label='')

share_grant(trusted_remote_user, key_id, timeout=30)





Returns list of correspondents ids

friend_add(idurl_or_global_id, alias='')

Add user to the list of friends


Remove user from the list of friends

suppliers_list(customer_idurl_or_global_id=None, verbose=False)

This method returns a list of suppliers - nodes which stores your encrypted data on own machines.

{'status': 'OK',
    'connected': '05-06-2016 13:06:05',
    'idurl': '',
    'files_count': 14,
    'position': 0,
    'contact_status': 'offline',
    'contact_state': 'OFFLINE'
 }, {
    'connected': '05-06-2016 13:04:57',
    'idurl': '',
    'files_count': 14,
    'position': 1,
    'contact_status': 'online'
    'contact_state': 'CONNECTED'


Execute a fire/hire process for given supplier, another random node will replace this supplier. As soon as new supplier is found and connected, rebuilding of all uploaded data will be started and the new node will start getting a reconstructed fragments.

{'status': 'OK', 'result': 'supplier will be replaced by new peer'}

supplier_change(index_or_idurl_or_global_id, new_supplier_idurl_or_global_id)

Doing same as supplier_replace() but new node must be provided by you - you can manually assign a supplier.

{'status': 'OK', 'result': 'supplier will be replaced by'}


Sends short requests to all suppliers to get their current statuses.

{'status': 'OK',  'result': 'requests to all suppliers was sent'}


Scans DHT network for key-value pairs related to given customer and returns a list of his "possible" suppliers.


List of customers - nodes who stores own data on your machine.

{'status': 'OK',
 'result': [ {  'idurl': '',
                'position': 0,
                'status': 'offline'


Stop supporting given customer, remove all his files from local disc, close connections with that node.

{'status': 'OK', 'result': 'customer rejected, 536870912 bytes were freed'}


Sends Identity packet to all customers to check their current statuses. Every node will reply with Ack packet on any valid incoming Identiy packet.

{'status': 'OK',  'result': 'requests to all customers was sent'}


Returns detailed statistics about your donated space usage.

{'status': 'OK',
 'result': [{
    'consumed': 0,
    'consumed_percent': '0%',
    'consumed_str': '0 bytes',
    'customers': [],
    'customers_num': 0,
    'donated': 1073741824,
    'donated_str': '1024 MB',
    'free': 1073741824,
    'old_customers': [],
    'real': 0,
    'used': 0,
    'used_percent': '0%',
    'used_str': '0 bytes'


Returns some info about your current usage of BitDust resources.

{'status': 'OK',
 'result': [{
    'available': 907163720,
    'available_per_supplier': 907163720,
    'available_per_supplier_str': '865.14 MB',
    'available_str': '865.14 MB',
    'needed': 1073741824,
    'needed_per_supplier': 1073741824,
    'needed_per_supplier_str': '1024 MB',
    'needed_str': '1024 MB',
    'suppliers_num': 2,
    'used': 166578104,
    'used_per_supplier': 166578104,
    'used_per_supplier_str': '158.86 MB',
    'used_percent': '0.155%',
    'used_str': '158.86 MB'


Returns detailed statistics about current usage of your local disk.

{'status': 'OK',
 'result': [{
    'backups': 0,
    'backups_str': '0 bytes',
    'customers': 0,
    'customers_str': '0 bytes',
    'diskfree': 103865696256,
    'diskfree_percent': '0.00162%',
    'diskfree_str': '96.73 GB',
    'disktotal': 63943473102848,
    'disktotal_str': '59552 GB',
    'temp': 48981,
    'temp_str': '47.83 KB',
    'total': 45238743,
    'total_percent': '0%',
    'total_str': '43.14 MB'


Returns a list of all currently running state machines.

{'status': 'OK',
 'result': [{
    'index': 1,
    'name': 'initializer',
    'state': 'READY',
    'timers': ''
  }, {
    'index': 2,
    'name': 'shutdowner',
    'state': 'READY',
    'timers': ''


Returns detailed info about all currently running network services.

{'status': 'OK',
 'result': [{
    'config_path': 'services/backup-db/enabled',
    'depends': ['service_list_files', 'service_data_motion'],
    'enabled': True,
    'index': 3,
    'installed': True,
    'name': 'service_backup_db',
    'state': 'ON'
  }, {
    'config_path': 'services/backups/enabled',
    'depends': ['service_list_files', 'service_employer', 'service_rebuilding'],
    'enabled': True,
    'index': 4,
    'installed': True,
    'name': 'service_backups',
    'state': 'ON'


Returns detailed info for single service.

{'status': 'OK',
 'result': [{
    'config_path': 'services/tcp-connections/enabled',
    'depends': ['service_network'],
    'enabled': True,
    'index': 24,
    'installed': True,
    'name': 'service_tcp_connections',
    'state': 'ON'


Start given service immediately. This method also set True for correspondent option in the program settings:

.bitdust/config/services/[service name]/enabled

If some other services, which is dependent on that service, were already enabled, they will be started also.

{'status': 'OK', 'result': 'service_tcp_connections was switched on'}


Stop given service immediately. It will also set False for correspondent option in the settings.

.bitdust/config/services/[service name]/enabled

Dependent services will be stopped as well.

{'status': 'OK', 'result': 'service_tcp_connections was switched off'}

service_restart(service_name, wait_timeout=10)

Stop given service and start it again, but only if it is already enabled. Do not change corresponding .bitdust/config/services/[service name]/enabled option. Dependent services will be "restarted" as well.

{'status': 'OK', 'result': 'service_tcp_connections was restarted'}


Returns detailed info about current network usage.

{'status': 'OK',
 'result': [{
    'in': {
        'failed_packets': 0,
        'total_bytes': 0,
        'total_packets': 0,
        'unknown_bytes': 0,
        'unknown_packets': 0
    'out': {
        '': 0,
        '': 0,
        'failed_packets': 8,
        'total_bytes': 0,
        'total_packets': 0,
        'unknown_bytes': 0,
        'unknown_packets': 0


Return list of incoming and outgoing packets.



Returns list of opened/active network connections. Argument wanted_protos can be used to select which protocols to list:

connections_list(wanted_protos=['tcp', 'udp'])


Return list of active sending/receiveing files.


user_ping(idurl_or_global_id, timeout=15, retries=2)

Sends Identity packet to remote peer and wait for Ack packet to check connection status. The "ping" command performs following actions: 1. Request remote identity source by idurl, 2. Sends my Identity to remote contact addresses, taken from identity, 3. Wait first Ack packet from remote peer, 4. Failed by timeout or identity fetching error. You can use this method to check and be sure that remote node is alive at the moment.

{'status': 'OK', 'result': '(signed.Packet[Ack(Identity) bob|bob for alice], in_70_19828906(DONE))'}


user_status_check(idurl_or_global_id, timeout=5)

user_search(nickname, attempts=1)

Starts nickname_observer() Automat to lookup existing nickname registered in DHT network.

user_observe(nickname, attempts=3)

Starts nickname_observer() Automat to lookup existing nickname registered in DHT network.



Starts nickname_holder() machine to register and keep your nickname in DHT network.

message_history(user, offset=0, limit=100)

Returns chat history with that user.

message_send(recipient, json_data, ping_timeout=30, message_ack_timeout=15)

Sends a text message to remote peer, recipient is a string with nickname or global_id.

{'status': 'OK', 'result': ['signed.Packet[Message(146681300413)]']}


This method can be used to listen and process incoming chat messages by specific consumer. If there are no messages received yet, this method will be waiting for any incomings. If some messages was already received, but not "consumed" yet method will return them imediately. After you got response and processed the messages you should call this method again to listen for more incomings again. This is simillar to message queue polling interface. If you do not "consume" messages, after 100 un-collected messages "consumer" will be dropped. Both, incoming and outgoing, messages will be populated here.

{'status': 'OK',
 'result': [{
    'type': 'private_message',
    'dir': 'incoming',
    'message_id': '123456788',
    'sender': 'messages$',
    'recipient': 'messages$',
    'data': {
        'message': 'Hello BitDust!'
    'time': 123456789


Sends broadcast message to all peers in the network.

Message must be provided in payload argument is a Json object.

WARNING! Please, do not send too often and do not send more then several kilobytes per message.

event_send(event_id, json_data=None)


network_stun(udp_port=None, dht_port=None)


Sends "reconnect" event to network_connector() Automat in order to refresh network connection.

{'status': 'OK', 'result': 'reconnected'}


Be sure BitDust software is connected to other nodes in the network. If all is good this method will block for wait_timeout seconds. In case of some network issues method will return result asap.


dht_node_find(node_id_64=None, layer_id=0)

dht_user_random(layer_id=0, count=1)

dht_value_get(key, record_type='skip_validation', layer_id=0)

dht_value_set(key, value, expire=None, record_type='skip_validation', layer_id=0)