Beginning
Principles
Development
Repositories
API methods
process_stop
process_restart
process_health
process_info
process_debug
config_get
config_set
configs_list
configs_tree
identity_get
identity_create
identity_backup
identity_recover
identity_erase
identity_rotate
identity_cache_list
key_get
keys_list
key_create
key_label
key_erase
key_share
key_audit
files_sync
files_list
file_exists
file_info
file_create
file_delete
files_uploads
file_upload_start
file_upload_stop
files_downloads
file_download_start
file_download_stop
file_explore
shares_list
share_create
share_delete
share_grant
share_open
share_close
share_history
groups_list
group_create
group_info
group_join
group_leave
group_share
friends_list
friend_add
friend_remove
user_ping
user_status
user_status_check
user_search
user_observe
message_history
message_conversations_list
message_send
message_send_group
message_receive
suppliers_list
supplier_change
suppliers_ping
suppliers_dht_lookup
customers_list
customer_reject
customers_ping
space_donated
space_consumed
space_local
services_list
service_info
service_start
service_stop
service_restart
packets_list
packets_stats
transfers_list
connections_list
streams_list
queues_list
queue_consumers_list
queue_producers_list
event_send
event_listen
network_stun
network_reconnect
network_connected
network_status
network_configuration
dht_node_find
dht_user_random
dht_value_get
dht_value_set
dht_local_db_dump
automats_list

BitDust API

Intro

Make sure your BitDust engine process is already running on that machine first.

There are multiple ways you can interract with the BitDust engine main process. Here you can find some examples of how to do that using different clients.

HTTP Rest API

The API server inside the engine is running on localhost:8180 by default. This can be modified via program settings.

You can use curl command to execute HTTP calls directly:

curl -X GET -H 'api_secret:abc' 'localhost:8180/process/health/v1'
{
  "execution": "0.000107",
  "status": "OK"
}
WebSocket

The WebSocket server inside the engine is running on localhost:8280 by default. This can be modified via program settings.

Here is a very basic example of a JavaScript WebSocket client call:

var websocket = null;
websocket = new WebSocket("ws://127.0.0.1:8280?api_secret=abc");
websocket.binaryType = "arraybuffer";
websocket.onopen = function() {
    websocket.send('{"command": "api_call", "method": "process_health", "kwargs": {} }');
};
websocket.onmessage = function(e) {
    if (typeof e.data == "string") {
        console.log("WebSocket message received: " + e.data);
    }
};
Command line shell client

Command line client is actually also using HTTP Rest API interface to interact with the main process.

To get more details about how to use BitDust via command line type in your terminal shell:

bitdust help

Access

Both HTTP and WebSocket interfaces are only accepting connections from the local host. This is an intended restriction to prevent any kind of access from outside of the host operation system to the main BitDust process. This way BitDust do not require user to have any kind of credentials to access the application.

To block access to BitDust API interface for non-authorized local clients a secret API token was introduced. That feature suppose to be enabled by default if you just installed the application for the first time.

To verify that secret token is in use you need to open the folder .bitdust/metadata/ and check if a file .bitdust/metadata/apisecret exists and is not empty. The file contains base64-formatted random token which is generated automatically by the application.

Authorized clients running on same operating system such as UI client and command line shell client will read that file from the disk and be able to access the API methods. Non-authorized local clients that do not have access to the host operating system will not be able to access the API.

API methods

You can find bellow a list of all API methods available at the moment.

process_stop()

Stop the main process immediately.

HTTP
curl -X GET 'localhost:8180/process/stop/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "process_stop", "kwargs": {} }');

process_restart()

Restart the main process.

HTTP
curl -X GET 'localhost:8180/process/restart/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "process_restart", "kwargs": {} }');

process_health()

Returns positive response if engine process is running. This method suppose to be used for health checks.

HTTP
curl -X GET 'localhost:8180/process/health/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "process_health", "kwargs": {} }');

process_info()

Returns overall information about current process. This method can be used for live monitoring and statistics.

HTTP
curl -X GET 'localhost:8180/process/info/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "process_info", "kwargs": {} }');

process_debug()

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

This is only useful if you already have executed the BitDust engine manually via shell console and would like to interrupt it and investigate things.

This call will block the main process and it will stop responding to any API calls.

HTTP
curl -X GET 'localhost:8180/process/debug/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "process_debug", "kwargs": {} }');

config_get(key, include_info=False)

Returns current key/value from the program settings.

HTTP
curl -X GET 'localhost:8180/config/get/v1?key=logs/debug-level'
WebSocket
websocket.send('{"command": "api_call", "method": "config_get", "kwargs": {"key": "logs/debug-level"} }');

config_set(key, value)

Set a value for given key option.

HTTP
curl -X POST 'localhost:8180/config/set/v1' -d '{"key": "logs/debug-level", "value": 12}'
WebSocket
websocket.send('{"command": "api_call", "method": "config_set", "kwargs": {"key": "logs/debug-level", "value": 12} }');

configs_list(sort=False, include_info=False)

Provide detailed info about all program settings.

HTTP
curl -X GET 'localhost:8180/config/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "configs_list", "kwargs": {} }');

configs_tree(include_info=False)

Returns all options as a tree structure, can be more suitable for UI operations.

HTTP
curl -X GET 'localhost:8180/config/tree/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "configs_tree", "kwargs": {} }');

identity_get(include_xml_source=False)

Returns your identity info.

HTTP
curl -X GET 'localhost:8180/identity/get/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "identity_get", "kwargs": {} }');

identity_create(username, preferred_servers=[], join_network=False)

Generates new private key and creates new identity for you to be able to communicate with other nodes in the network.

Parameter username defines filename of the new identity, can not be changed anymore.

By default that method only connects to ID servers to be able to register a new identity file for you. If you also pass join_network=True it will start all network services right after that and will make you connected to the BitDust network automatically.

HTTP
curl -X POST 'localhost:8180/identity/create/v1' -d '{"username": "alice", "join_network": 1}'
WebSocket
websocket.send('{"command": "api_call", "method": "identity_create", "kwargs": {"username": "alice", "join_network": 1} }');

identity_backup(destination_filepath)

Creates local file at destination_filepath on your disk drive with a backup copy of your private key and recent IDURL.

You can use that file to restore identity in case of lost data using identity_recover() API method.

WARNING! Make sure to always have a backup copy of your identity secret key in a safe place - there is no other way to restore your data in case of lost.

HTTP
curl -X POST 'localhost:8180/identity/backup/v1' -d '{"destination_filepath": "/tmp/alice_backup.key"}'
WebSocket
websocket.send('{"command": "api_call", "method": "identity_backup", "kwargs": {"destination_filepath": "/tmp/alice_backup.key"} }');

identity_recover(private_key_source, known_idurl=None, join_network=False)

Restores your identity from backup copy.

Input parameter private_key_source must contain your latest IDURL and the private key as openssh formated string.

HTTP
curl -X POST 'localhost:8180/identity/recover/v1' -d '{"private_key_source": "http://some-host.com/alice.xml\n-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKC..."}'
WebSocket
websocket.send('{"command": "api_call", "method": "identity_recover", "kwargs": {"private_key_source": "http://some-host.com/alice.xml\n-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKC..."} }');

identity_erase(erase_private_key=False)

Method will erase current identity file and the private key (optionally). All network services will be stopped first.

HTTP
curl -X DELETE 'localhost:8180/identity/erase/v1' -d '{"erase_private_key": true}'
WebSocket
websocket.send('{"command": "api_call", "method": "identity_erase", "kwargs": {"erase_private_key": true} }');

identity_rotate()

Rotate your identity sources and republish identity file on another ID server even if current ID servers are healthy.

Normally that procedure is executed automatically when current process detects unhealthy ID server among your identity sources.

This method is provided for testing and development purposes.

HTTP
curl -X PUT 'localhost:8180/identity/rotate/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "identity_rotate", "kwargs": {} }');

identity_cache_list()

Returns list of all cached locally identity files received from other users.

HTTP
curl -X GET 'localhost:8180/identity/cache/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "identity_cache_list", "kwargs": {} }');

key_get(key_id, include_private=False)

Returns details of the registered public or private key.

Use include_private=True if you also need a private key (as openssh formated string) to be present in the response.

HTTP
curl -X GET 'localhost:8180/key/get/v1?key_id=abcd1234$alice@server-a.com'
WebSocket
websocket.send('{"command": "api_call", "method": "key_get", "kwargs": {"key_id": "abcd1234$alice@server-a.com"} }');

keys_list(sort=False, include_private=False)

List details for all registered public and private keys.

Use include_private=True if you also need a private key (as openssh formated string) to be present in the response.

HTTP
curl -X GET 'localhost:8180/key/list/v1?include_private=1'
WebSocket
websocket.send('{"command": "api_call", "method": "keys_list", "kwargs": {"include_private": 1} }');

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

Generate new RSA private key and add it to the list of registered keys with a new key_id.

Optional input parameter key_size can be 1024, 2048, 4096. If key_size was not passed, default value will be populated from the personal/private-key-size program setting.

Parameter label can be used to attach some meaningful information for the user to display in the UI.

Use include_private=True if you also need a private key (as openssh formated string) to be present in the response.

HTTP
curl -X POST 'localhost:8180/key/create/v1' -d '{"key_alias": "abcd1234", "key_size": 1024, "label": "Cats and Dogs"}'
WebSocket
websocket.send('{"command": "api_call", "method": "key_create", "kwargs": {"key_alias": "abcd1234", "key_size": 1024, "label": "Cats and Dogs"} }');

key_label(key_id, label)

Set new label for the given key.

HTTP
curl -X POST 'localhost:8180/key/label/v1' -d '{"key_id": "abcd1234$alice@server-a.com", "label": "Man and Woman"}'
WebSocket
websocket.send('{"command": "api_call", "method": "key_label", "kwargs": {"key_id": "abcd1234$alice@server-a.com", "label": "Man and Woman"} }');

key_erase(key_id)

Unregister and remove given key from the list of known keys and erase local file.

HTTP
curl -X DELETE 'localhost:8180/key/erase/v1' -d '{"key_id": "abcd1234$alice@server-a.com"}'
WebSocket
websocket.send('{"command": "api_call", "method": "key_erase", "kwargs": {"key_id": "abcd1234$alice@server-a.com"} }');

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

Connects to remote user and transfer given public or private key to that node. This way you can share access to files/groups/resources with other users in the network.

If you pass include_private=True also private part of the key will be shared, otherwise only public part.

HTTP
curl -X PUT 'localhost:8180/key/share/v1' -d '{"key_id": "abcd1234$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"}'
WebSocket
websocket.send('{"command": "api_call", "method": "key_share", "kwargs": {"key_id": "abcd1234$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"} }');

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

Connects to remote node identified by untrusted_user_id parameter and request audit of given public or private key key_id on that node.

Returns positive result if audit process succeed - that means remote user really possess the key.

HTTP
curl -X POST 'localhost:8180/key/audit/v1' -d '{"key_id": "abcd1234$alice@server-a.com", "untrusted_user_id": "carol@computer-c.net", "is_private": 1}'
WebSocket
websocket.send('{"command": "api_call", "method": "key_audit", "kwargs": {"key_id": "abcd1234$alice@server-a.com", "untrusted_user_id": "carol@computer-c.net", "is_private": 1} }');

files_sync()

This should re-start "data synchronization" process with your remote suppliers.

Normally all communications and synchronizations are handled automatically, so you do not need to call that method.

This method is provided for testing and development purposes.

HTTP
curl -X GET 'localhost:8180/file/sync/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "files_sync", "kwargs": {} }');

files_list(remote_path=None, key_id=None, recursive=True, all_customers=False, include_uploads=False, include_downloads=False)

Returns list of known files registered in the catalog under given remote_path folder. By default returns items from root of the catalog.

If key_id is passed will only return items encrypted using that key.

Use all_customers=True to get list of all registered files - including received/shared to you by another user.

You can also use include_uploads and include_downloads parameters to get more info about currently running uploads and downloads.

HTTP
curl -X GET 'localhost:8180/file/list/v1?remote_path=abcd1234$alice@server-a.com:pictures/cats/'
WebSocket
websocket.send('{"command": "api_call", "method": "files_list", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:pictures/cats/"} }');

file_exists(remote_path)

Returns positive result if file or folder with such remote_path already exists in the catalog.

HTTP
curl -X GET 'localhost:8180/file/exists/v1?remote_path=abcd1234$alice@server-a.com:pictures/cats/pussy.png'
WebSocket
websocket.send('{"command": "api_call", "method": "file_exists", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:pictures/cats/pussy.png"} }');

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

Returns detailed info about given file or folder in the catalog.

You can also use include_uploads and include_downloads parameters to get more info about currently running uploads and downloads.

HTTP
curl -X GET 'localhost:8180/file/info/v1?remote_path=abcd1234$alice@server-a.com:pictures/dogs/bobby.jpeg'
WebSocket
websocket.send('{"command": "api_call", "method": "file_info", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:pictures/dogs/bobby.jpeg"} }');

file_create(remote_path, as_folder=False, exist_ok=False, force_path_id=None)

Creates new file in the catalog, but do not upload any data to the network yet.

This method only creates a "virtual ID" for the new data.

Pass as_folder=True to create a virtual folder instead of a file.

HTTP
curl -X POST 'localhost:8180/file/create/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:movies/travels/safari.mp4"}'
WebSocket
websocket.send('{"command": "api_call", "method": "file_create", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:movies/travels/safari.mp4"} }');

file_delete(remote_path)

Removes virtual file or folder from the catalog and also notifies your remote suppliers to clean up corresponding uploaded data.

HTTP
curl -X DELETE 'localhost:8180/file/delete/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:cars/ferrari.gif"}'
WebSocket
websocket.send('{"command": "api_call", "method": "file_delete", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/ferrari.gif"} }');

files_uploads(include_running=True, include_pending=True)

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

HTTP
curl -X GET 'localhost:8180/file/upload/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "files_uploads", "kwargs": {} }');

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

Starts a new file or folder (including all sub-folders and files) upload from local_path on your disk drive to the virtual location remote_path in the catalog. New "version" of the data will be created for given catalog item and uploading task started.

You can use wait_result=True to block the response from that method until uploading finishes or fails (makes no sense for large uploads).

Parameter open_share can be useful if you uploading data into a "shared" virtual path using another key that shared to you.

HTTP
curl -X POST 'localhost:8180/file/upload/start/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg", "local_path": "/tmp/fiat.jpeg"}'
WebSocket
websocket.send('{"command": "api_call", "method": "file_upload_start", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg", "local_path": "/tmp/fiat.jpeg"} }');

file_upload_stop(remote_path)

Useful method if you need to interrupt and cancel already running uploading task.

HTTP
curl -X POST 'localhost:8180/file/upload/stop/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"}'
WebSocket
websocket.send('{"command": "api_call", "method": "file_upload_stop", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"} }');

files_downloads()

Returns a list of currently running downloading tasks.

HTTP
curl -X GET 'localhost:8180/file/download/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "files_downloads", "kwargs": {} }');

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:

  • "virtual" path of the file
  • internal path ID in the catalog
  • full data version identifier with path ID and version name

It is possible to select the destination folder to extract requested files to. By default this method uses specified value from paths/restore program setting or user home folder.

You can use wait_result=True to block the response from that method until downloading finishes or fails (makes no sense for large files).

WARNING! Your existing local data in destination_path will be overwritten!

HTTP
curl -X POST 'localhost:8180/file/download/start/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:movies/back_to_the_future.mp4", "local_path": "/tmp/films/"}'
WebSocket
websocket.send('{"command": "api_call", "method": "file_download_start", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:movies/back_to_the_future.mp4", "local_path": "/tmp/films/"} }');

file_download_stop(remote_path)

Abort currently running restore process.

HTTP
curl -X POST 'localhost:8180/file/download/stop/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"}'
WebSocket
websocket.send('{"command": "api_call", "method": "file_download_stop", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"} }');

file_explore(local_path)

Useful method to be executed from the UI right after downloading is finished.

It will open default OS file manager and display given local_path to the user so he can do something with the file.

HTTP
curl -X GET 'localhost:8180/file/explore/v1?local_path=/tmp/movies/back_to_the_future.mp4'
WebSocket
websocket.send('{"command": "api_call", "method": "file_explore", "kwargs": {"local_path": "/tmp/movies/back_to_the_future.mp4"} }');

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

Returns a list of registered "shares" - encrypted locations where you can upload/download files.

Use only_active=True to select only connected shares.

Parameters include_mine and include_granted can be used to filter shares created by you, or by other users that shared a key with you before.

HTTP
curl -X GET 'localhost:8180/share/list/v1?only_active=1'
WebSocket
websocket.send('{"command": "api_call", "method": "shares_list", "kwargs": {"only_active": 1} }');

share_create(owner_id=None, key_size=None, label="")

Creates a new "share" - virtual location where you or other users can upload/download files.

This method generates a new RSA private key that will be used to encrypt and decrypt files belongs to that share.

By default you are the owner of the new share and uploaded files will be stored by your suppliers. You can also use owner_id parameter if you wish to set another owner for that new share location. In that case files will be stored not on your suppliers but on his/her suppliers, if another user authorized the share.

Optional input parameter key_size can be 1024, 2048, 4096. If key_size was not passed, default value will be populated from the personal/private-key-size program setting.

Parameter label can be used to attach some meaningful information about that share location.

HTTP
curl -X POST 'localhost:8180/share/create/v1' -d '{"label": "my summer holidays"}'
WebSocket
websocket.send('{"command": "api_call", "method": "share_create", "kwargs": {"label": "my summer holidays"} }');

share_delete(key_id)

Stop the active share identified by the key_id and erase the private key.

HTTP
curl -X DELETE 'localhost:8180/share/delete/v1' -d '{"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"}'
WebSocket
websocket.send('{"command": "api_call", "method": "share_delete", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"} }');

share_grant(key_id, trusted_user_id, timeout=30)

Provide access to given share identified by key_id to another trusted user.

This method will transfer private key to remote user trusted_user_id and you both will be able to upload/download file to the shared location.

HTTP
curl -X PUT 'localhost:8180/share/grant/v1' -d '{"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"}'
WebSocket
websocket.send('{"command": "api_call", "method": "share_grant", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"} }');

share_open(key_id)

Activates given share and initiate required connections to remote suppliers to make possible to upload and download shared files.

HTTP
curl -X PUT 'localhost:8180/share/open/v1' -d '{"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"}'
WebSocket
websocket.send('{"command": "api_call", "method": "share_open", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"} }');

share_close(key_id)

Disconnects and deactivate given share location.

HTTP
curl -X PUT 'localhost:8180/share/close/v1' -d '{"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"}'
WebSocket
websocket.send('{"command": "api_call", "method": "share_close", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"} }');

share_history()

Method is not implemented yet.

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

Returns a list of registered message groups.

Use only_active=True to select only connected and active groups.

Parameters include_mine and include_granted can be used to filter groups created by you, or by other users that shared a key with you before.

HTTP
curl -X GET 'localhost:8180/group/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "groups_list", "kwargs": {} }');

group_create(creator_id=None, key_size=None, label="", timeout=20)

Creates a new messaging group.

This method generates a new RSA private key that will be used to encrypt and decrypt messages streamed thru that group.

Optional input parameter key_size can be 1024, 2048, 4096. If key_size was not passed, default value will be populated from the personal/private-key-size program setting.

Parameter label can be used to attach some meaningful information about that group.

HTTP
curl -X POST 'localhost:8180/group/create/v1' -d '{"label": "chat with my friends"}'
WebSocket
websocket.send('{"command": "api_call", "method": "group_create", "kwargs": {"label": "chat with my friends"} }');

group_info(group_key_id)

Returns detailed info about the message group identified by group_key_id.

HTTP
curl -X GET 'localhost:8180/group/info/v1?group_key_id=group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com'
WebSocket
websocket.send('{"command": "api_call", "method": "group_info", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"} }');

group_join(group_key_id)

Activates given messaging group to be able to receive streamed messages or send a new message to the group.

HTTP
curl -X POST 'localhost:8180/group/join/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"}'
WebSocket
websocket.send('{"command": "api_call", "method": "group_join", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"} }');

group_leave(group_key_id, erase_key=False)

Deactivates given messaging group. If erase_key=True will also erase the private key related to that group.

HTTP
curl -X DELETE 'localhost:8180/group/leave/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"}'
WebSocket
websocket.send('{"command": "api_call", "method": "group_leave", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"} }');

group_share(group_key_id, trusted_user_id, timeout=30)

Provide access to given group identified by group_key_id to another trusted user.

This method will transfer private key to remote user trusted_user_id inviting him to the messaging group.

HTTP
curl -X PUT 'localhost:8180/group/share/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"}'
WebSocket
websocket.send('{"command": "api_call", "method": "group_share", "kwargs": {"key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"} }');

friends_list()

Returns list of registered correspondents.

HTTP
curl -X GET 'localhost:8180/friend/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "friends_list", "kwargs": {} }');

friend_add(trusted_user_id, alias="", share_person_key=True)

Add user to the list of correspondents.

You can attach an alias to that user as a label to be displayed in the UI.

HTTP
curl -X POST 'localhost:8180/friend/add/v1' -d '{"trusted_user_id": "dave@device-d.gov", "alias": "SuperMario"}'
WebSocket
websocket.send('{"command": "api_call", "method": "friend_add", "kwargs": {"trusted_user_id": "dave@device-d.gov", "alias": "SuperMario"} }');

friend_remove(user_id)

Removes given user from the list of correspondents.

HTTP
curl -X DELETE 'localhost:8180/friend/add/v1' -d '{"user_id": "dave@device-d.gov"}'
WebSocket
websocket.send('{"command": "api_call", "method": "friend_add", "kwargs": {"user_id": "dave@device-d.gov"} }');

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

Sends Identity packet to remote peer and wait for an Ack packet to check connection status.

Method can be used to check and verify that remote node is on-line at the moment (if you are also on-line).

HTTP
curl -X GET 'localhost:8180/user/ping/v1?user_id=carol@computer-c.net'
WebSocket
websocket.send('{"command": "api_call", "method": "suppliers_ping", "kwargs": {} }');

user_status(user_id)

Returns short info about current on-line status of the given user.

HTTP
curl -X GET 'localhost:8180/user/status/v1?user_id=carol@computer-c.net'
WebSocket
websocket.send('{"command": "api_call", "method": "user_status", "kwargs": {"user_id": "carol@computer-c.net"} }');

user_status_check(user_id, timeout=5)

Returns current online status of a user and only if node is known but disconnected performs "ping" operation.

HTTP
curl -X GET 'localhost:8180/user/status/check/v1?user_id=carol@computer-c.net'
WebSocket
websocket.send('{"command": "api_call", "method": "user_status_check", "kwargs": {"user_id": "carol@computer-c.net"} }');

Doing lookup of a single nickname registered in the DHT network.

HTTP
curl -X GET 'localhost:8180/user/search/v1?nickname=carol'
WebSocket
websocket.send('{"command": "api_call", "method": "user_search", "kwargs": {"nickname": "carol"} }');

user_observe(nickname, attempts=3)

Reads all records registered for given nickname in the DHT network.

It could be that multiple users chosen same nickname when creating an identity.

HTTP
curl -X GET 'localhost:8180/user/observe/v1?nickname=carol'
WebSocket
websocket.send('{"command": "api_call", "method": "user_observe", "kwargs": {"nickname": "carol"} }');

message_history(recipient_id=None, sender_id=None, message_type=None, offset=0, limit=100)

Returns chat communications history stored for given user or messaging group.

HTTP
curl -X GET 'localhost:8180/message/history/v1?message_type=group_message&recipient_id=group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com'
WebSocket
websocket.send('{"command": "api_call", "method": "message_history", "kwargs": {"recipient_id" : "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "message_type": "group_message"} }');

message_conversations_list(message_types=[], offset=0, limit=100)

Returns list of all known conversations with other users. Parameter message_types can be used to select conversations of specific types: "groupmessage", "privatemessage", "personal_message".

HTTP
curl -X GET 'localhost:8180/message/conversation/v1?message_types=group_message,private_message'
WebSocket
websocket.send('{"command": "api_call", "method": "message_conversations_list", "kwargs": {"message_types" : ["group_message", "private_message"]} }');

message_send(recipient_id, data, ping_timeout=30, message_ack_timeout=15)

Sends a private message to remote peer, recipient_id is a string with a nickname, global_id or IDURL of the remote user.

Message will be encrypted first with public key of the recipient. Public key must be already registered locally or populated from remote identity file. Corresponding key will be recognized based on recipient_id parameter.

Recipient will receive incoming message of type "private_message" and de-crypt it. If recipient is listening on the new private messages it will be marked as "consumed".

Input data must be a JSON dictionary.

HTTP
curl -X POST 'localhost:8180/message/send/v1' -d '{"recipient_id": "carlos@computer-c.net", "data": {"message": "Hola Amigo!"}}'
WebSocket
websocket.send('{"command": "api_call", "method": "message_send", "kwargs": {"recipient_id": "carlos@computer-c.net", "data": {"message": "Hola Amigos!"}} }');

message_send_group(group_key_id, data)

Sends a "group_message" to a group of users.

Input data must be a JSON dictionary.

HTTP
curl -X POST 'localhost:8180/message/send/group/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "data": {"message": "Hola Amigos!"}}'
WebSocket
websocket.send('{"command": "api_call", "method": "message_send_group", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "data": {"message": "Hola Amigos!"}} }');

message_receive(consumer_callback_id, direction="incoming", message_types="private_message,group_message", polling_timeout=60)

This method can be used by clients to listen and process streaming messages.

If there are no pending messages received yet in the stream, this method will block and will be waiting for any message to come.

If some messages are already waiting in the stream to be consumed method will return them immediately. As soon as client received and processed the response messages are marked as "consumed" and released from the stream.

Client should call that method again to listen for next messages in the stream. You can use polling_timeout parameter to control blocking for receiving duration. This is very similar to a long polling technique.

Once client stopped calling that method and do not "consume" messages anymor given consumer_callback_id will be dropped after 100 non-collected messages.

You can set parameter direction=outgoing to only populate messages you are sending to others - can be useful for UI clients.

Also you can use parameter message_types to select only specific types of messages: "privatemessage" or "groupmessage".

This method is only make sense for HTTP interface, because using a WebSocket client will receive streamed message directly.

HTTP
curl -X GET 'localhost:8180/message/receive/my-client-group-messages/v1?message_types=group_message'

suppliers_list(customer_id=None, verbose=False)

This method returns a list of your suppliers. Those nodes stores your encrypted file or file uploaded by other users that still belongs to you.

Your BitDust node also sometimes need to connect to suppliers of other users to upload or download shared data. Those external suppliers lists are cached and can be selected here with customer_id optional parameter.

HTTP
curl -X GET 'localhost:8180/supplier/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "suppliers_list", "kwargs": {} }');

supplier_change(position=None, supplier_id=None, new_supplier_id=None)

The method will execute a fire/hire process for given supplier. You can specify which supplier to be replaced by position or ID.

If optional parameter new_supplier_id was not specified another random node will be found via DHT network and it will replace the current supplier. Otherwise new_supplier_id must be an existing node in the network and the process will try to connect and use that node as a new supplier.

As soon as new node is found and connected, rebuilding of all uploaded data will be automatically started and new supplier will start getting reconstructed fragments of your data piece by piece.

HTTP
curl -X POST 'localhost:8180/supplier/change/v1' -d '{"position": 1, "new_supplier_id": "carol@computer-c.net"}'
WebSocket
websocket.send('{"command": "api_call", "method": "supplier_change", "kwargs": {"position": 1, "new_supplier_id": "carol@computer-c.net"} }');

suppliers_ping()

Sends short requests to all suppliers to verify current connection status.

HTTP
curl -X POST 'localhost:8180/supplier/ping/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "suppliers_ping", "kwargs": {} }');

suppliers_dht_lookup(customer_id=None)

Scans DHT network for key-value pairs related to given customer and returns a list its suppliers.

HTTP
curl -X GET 'localhost:8180/supplier/list/dht/v1?customer_id=alice@server-a.com'
WebSocket
websocket.send('{"command": "api_call", "method": "suppliers_dht_lookup", "kwargs": {"customer_id": "alice@server-a.com"} }');

customers_list(verbose=False)

Method returns list of your customers - nodes for whom you are storing data on that host.

HTTP
curl -X GET 'localhost:8180/customer/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "customers_list", "kwargs": {} }');

customer_reject(customer_id)

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

HTTP
curl -X DELETE 'localhost:8180/customer/reject/v1' -d '{"customer_id": "dave@device-d.gov"}'
WebSocket
websocket.send('{"command": "api_call", "method": "customer_reject", "kwargs": {"customer_id": "dave@device-d.gov"} }');

customers_ping()

Check current on-line status of all customers.

HTTP
curl -X POST 'localhost:8180/customer/ping/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "customers_ping", "kwargs": {} }');

space_donated()

Returns detailed info about quotas and usage of the storage space you donated to your customers.

HTTP
curl -X GET 'localhost:8180/space/donated/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "space_donated", "kwargs": {} }');

space_consumed()

Returns info about current usage of the storage space provided by your suppliers.

HTTP
curl -X GET 'localhost:8180/space/consumed/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "space_consumed", "kwargs": {} }');

space_local()

Returns info about current usage of your local disk drive.

HTTP
curl -X GET 'localhost:8180/space/local/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "space_local", "kwargs": {} }');

services_list(with_configs=False)

Returns detailed info about all currently running network services.

Pass with_configs=True to also see current program settings values related to each service.

This is a very useful method when you need to investigate a problem in the software.

HTTP
curl -X GET 'localhost:8180/service/list/v1?with_configs=1'
WebSocket
websocket.send('{"command": "api_call", "method": "services_list", "kwargs": {"with_configs": 1} }');

service_info(service_name)

Returns detailed info about single service.

HTTP
curl -X GET 'localhost:8180/service/info/service_private_groups/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "service_info", "kwargs": {"service_name": "service_private_groups"} }');

service_start(service_name)

Starts given service immediately.

This method also set True for correspondent option in the program settings to mark the service as enabled:

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

Other dependent services, if they were enabled before but stopped, also will be started.

HTTP
curl -X POST 'localhost:8180/service/start/service_supplier/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "service_start", "kwargs": {"service_name": "service_supplier"} }');

service_stop(service_name)

Stop given service immediately.

This method also set False for correspondent option in the program settings to mark the service as disabled:

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

Dependent services will be stopped as well but will not be disabled.

HTTP
curl -X POST 'localhost:8180/service/stop/service_supplier/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "service_stop", "kwargs": {"service_name": "service_supplier"} }');

service_restart(service_name, wait_timeout=10)

This method will stop given service and start it again, but only if it is already enabled. It will not modify corresponding option for that service in the program settings.

All dependent services will be restarted as well.

Very useful method when you need to reload some parts of the application without full process restart.

HTTP
curl -X POST 'localhost:8180/service/restart/service_customer/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "service_restart", "kwargs": {"service_name": "service_customer"} }');

packets_list()

Returns list of incoming and outgoing signed packets running at the moment.

HTTP
curl -X GET 'localhost:8180/packet/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "packets_list", "kwargs": {} }');

packets_stats()

Returns detailed info about overall network usage.

HTTP
curl -X GET 'localhost:8180/packet/stats/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "packets_stats", "kwargs": {} }');

transfers_list()

Returns list of current data fragments transfers to/from suppliers.

HTTP
curl -X GET 'localhost:8180/transfer/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "transfers_list", "kwargs": {} }');

connections_list(protocols=None)

Returns list of opened/active network connections.

Argument protocols can be used to select which protocols to be present in the response:

HTTP
curl -X GET 'localhost:8180/connection/list/v1?protocols=tcp,udp,proxy'
WebSocket
websocket.send('{"command": "api_call", "method": "connections_list", "kwargs": {"protocols": ["tcp", "udp", "proxy"]} }');

streams_list(protocols=None)

Returns list of running streams of data fragments with recent upload/download progress percentage.

HTTP
curl -X GET 'localhost:8180/stream/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "streams_list", "kwargs": {} }');

queues_list()

Returns list of registered streaming queues.

HTTP
curl -X GET 'localhost:8180/queue/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "queues_list", "kwargs": {} }');

queue_consumers_list()

Returns list of registered queue consumers.

HTTP
curl -X GET 'localhost:8180/queue/consumer/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "queue_consumers_list", "kwargs": {} }');

queue_producers_list()

Returns list of registered queue producers.

HTTP
curl -X GET 'localhost:8180/queue/producer/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "queue_producers_list", "kwargs": {} }');

event_send(event_id, data=None)

Method will generate and inject a new event inside the main process.

This method is provided for testing and development purposes.

HTTP
curl -X POST 'localhost:8180/event/send/client-event-abc/v1' -d '{"data": {"some_key": "some_value"}}'
WebSocket
websocket.send('{"command": "api_call", "method": "event_send", "kwargs": {"event_id": "client-event-produced", "data": {"some_key": "some_value"}} }');

event_listen(consumer_callback_id)

This method can be used by clients to listen and process all events fired inside the main process.

If there are no pending events fired yet, this method will block and will be waiting for any new event.

If some messages are already waiting in the stream to be consumed method will return them immediately. As soon as client received and processed the response events are marked as "consumed" and released from the buffer.

Client should call that method again to listen for next events. This is very similar to a long polling technique.

This method is only make sense for HTTP interface, because using a WebSocket client will receive application events directly.

HTTP
curl -X GET 'localhost:8180/event/listen/my-client-event-hook/v1'

network_stun(udp_port=None, dht_port=None)

Begins network STUN process to detect your network configuration and current external IP address of that host.

HTTP
curl -X GET 'localhost:8180/network/stun/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "network_stun", "kwargs": {} }');

network_reconnect()

Method can be used to refresh network status and restart all internal connections.

HTTP
curl -X GET 'localhost:8180/network/reconnect/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "network_reconnect", "kwargs": {} }');

network_connected(wait_timeout=5)

Method can be used by clients to ensure BitDust application 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 immediately.

HTTP
curl -X GET 'localhost:8180/network/connected/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "network_connected", "kwargs": {} }');

network_status(suppliers=False, customers=False, cache=False, tcp=False, udp=False, proxy=False, dht=False)

Returns detailed info about current network status, protocols and active connections.

HTTP
curl -X GET 'localhost:8180/network/status/v1?cache=1&suppliers=1&dht=1'
WebSocket
websocket.send('{"command": "api_call", "method": "network_status", "kwargs": {"cache": 1, "suppliers": 1, "dht": 1} }');

network_configuration()

Returns details about network services.

HTTP
curl -X GET 'localhost:8180/network/configuration/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "network_configuration", "kwargs": {} }');

dht_node_find(node_id_64=None, layer_id=0)

Lookup "closest" (in terms of hashes and cryptography) DHT nodes to a given node_id_64 value.

Method can be also used to pick a random DHT node from the network if you do not pass any value to node_id_64.

Parameter layer_id specifies which layer of the routing table to be used.

HTTP
curl -X GET 'localhost:8180/dht/node/find/v1?node_id_64=4271c8f079695d77f80186ac9365e3df949ff74d'
WebSocket
websocket.send('{"command": "api_call", "method": "dht_node_find", "kwargs": {"node_id_64": "4271c8f079695d77f80186ac9365e3df949ff74d"} }');

dht_user_random(layer_id=0, count=1)

Pick random live nodes from BitDust network.

Method is used during services discovery, for example when you need to hire a new supplier to store your data.

Parameter layer_id specifies which layer of the routing table to be used.

HTTP
curl -X GET 'localhost:8180/dht/user/random/v1?count=2&layer_id=2'
WebSocket
websocket.send('{"command": "api_call", "method": "dht_node_find", "kwargs": {"count": 2, "layer_id": 2} }');

dht_value_get(key, record_type="skip_validation", layer_id=0, use_cache_ttl=None)

Fetch single key/value record from DHT network.

HTTP
curl -X GET 'localhost:8180/dht/value/get/v1?key=abcd'
WebSocket
websocket.send('{"command": "api_call", "method": "dht_value_get", "kwargs": {"key": "abcd"} }');

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

Writes given key/value record into DHT network. Input parameter value must be a JSON value.

HTTP
curl -X POST 'localhost:8180/dht/value/set/v1' -d '{"key": "abcd", "value": {"text": "A-B-C-D"}}'
WebSocket
websocket.send('{"command": "api_call", "method": "dht_value_set", "kwargs": {"key": "abcd", "value": {"text": "A-B-C-D"}} }');

dht_local_db_dump()

Method used for testing purposes, returns full list of all key/values stored locally on that DHT node.

HTTP
curl -X GET 'localhost:8180/dht/db/dump/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "dht_local_db_dump", "kwargs": {} }');

automats_list()

Returns a list of all currently running state machines.

This is a very useful method when you need to investigate a problem in the software.

HTTP
curl -X GET 'localhost:8180/automat/list/v1'
WebSocket
websocket.send('{"command": "api_call", "method": "automats_list", "kwargs": {} }');