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.

enable_model_listener(model_name, request_all=False)

When using WebSocket API interface you can get advantage of real-time data streaming and receive additional information when certain things are changing in the engine. Any updates to those instances will be automatically populated to the WebSocket connection.

For each model this method suppose to be called only once to switch on the live streaming for that data type.

When request_all=True the engine will immediately populate one time all of the data objects of given type to the WebSocket. This way client will be able to catch and store everything on the front-side and after that use only live streaming to receive the updates for given data model.

WebSocket

websocket.send('{"command": "api_call", "method": "enable_model_listener", "kwargs": {"model_name": "key"} }');

disable_model_listener(model_name)

Stop live streaming of all updates regarding given data type to the WebSocket connection.

WebSocket

websocket.send('{"command": "api_call", "method": "disable_model_listener", "kwargs": {"model_name": "key"} }');

request_model_data(model_name, query_details=None)

The engine will try to immediately populate all data related to the given model type to the WebSocket, one time only.

WebSocket

websocket.send('{"command": "api_call", "method": "request_model_data", "kwargs": {"model_name": "key"} }');

process_stop(instant=True)

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 until pdb shell is released.

HTTP

curl -X GET 'localhost:8180/process/debug/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "process_debug", "kwargs": {} }');

devices_list(sort=False)

List all registered configurations of your configured API devices.

API Device provide remote access to BitDust node running on that machine.

Remote device (often mobile phone, tablet, etc.) acts as a thin-client and allows you to access and manage this BitDust node via secure web socket connection. To be able to access this BitDust node from your mobile phone, you first need to configure and authorize API device.

HTTP

curl -X GET 'localhost:8180/device/list/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "devices_list", "kwargs": {} }');

device_info(name)

Returns detailed info about given API device.

HTTP

curl -X GET 'localhost:8180/device/info/v1?name=my_iPhone_12'

WebSocket

websocket.send('{"command": "api_call", "method": "device_info", "kwargs": {"name": "my_iPhone_12"} }');

device_add(name, routed=False, activate=True, wait_listening=False, web_socket_port=None, key_size=None)

The name parameter is a user-specified local name to be used to identify new API device. You can use ASCII characters, numbers and underscore.

When parameter routed is set to true new API device configuration will be using intermediate BitDust nodes to route encrypted web socket traffic from your client-device to the BitDust node.

Such setup is especially useful to connect your pair your mobile phone to a PC running BitDust node at home. Routed traffic is end-to-end encrypted and intermediate BitDust nodes have no way to read your private data.

The web_socket_port parameter from other side is only used in non-routed setup. In that case you are connecting from your mobile phone directly to the opened web socket of the running BitDust node. You have to have a static publicly-accessible IP address and opened port on your machine in order to make this working.

Such setup is more suitable when you are hosting your BitDust node on the cloud-server and want to access it from your mobile device, laptop or home PC.

If you pass activate=true, new device will be activated and started accepting incoming connections right away.

HTTP

curl -X POST 'localhost:8180/device/add/v1' -d '{"name": "my_iPhone_12", "routed": true}'

WebSocket

websocket.send('{"command": "api_call", "method": "device_add", "kwargs": {"name": "my_iPhone_12", "routed": true} }');

device_start(name, wait_listening=False)

Activates given API device and start accepting incoming connections.

HTTP

curl -X POST 'localhost:8180/device/start/v1' -d '{"name": "my_iPhone_12"}'

WebSocket

websocket.send('{"command": "api_call", "method": "device_start", "kwargs": {"name": "my_iPhone_12"} }');

device_authorization_reset(name, start=True, wait_listening=False)

device_client_code_input(name, client_code)

device_stop(name)

This will stop accepting incoming connections from given API device and deactivate it.

Stored configuration will not be removed and the device can be started again later.

HTTP

curl -X POST 'localhost:8180/device/stop/v1 -d '{"name": "my_iPhone_12"}'

WebSocket

websocket.send('{"command": "api_call", "method": "device_stop", "kwargs": {"name": "my_iPhone_12"} }');

device_remove(name)

Removes stored configuration of the given API device.

HTTP

curl -X DELETE 'localhost:8180/device/remove/v1' -d '{"name": "my_iPhone_12"}'

WebSocket

websocket.send('{"command": "api_call", "method": "device_remove", "kwargs": {"name": "my_iPhone_12"} }');

network_create(url)

This method is a way to load a new custom network configuration for this BitDust node.

You can always use the default network configuration - this is a public network available for everyone. The seed nodes are maintained by the founders of the project.

But you can also run your own hardware and maintain a number of your own BitDust seed nodes. This is a way to run a completely isolated and private BitDust network.

All BitDust users on your network will need to run this method once on their devices to load the custom network configuration and make software know where to connect for the first time.

The url parameter is a web location of the JSON-formatted network configuration file. It can also be a full path to the local file where the network configuration is stored on your drive.

HTTP

curl -X POST 'localhost:8180/network/create/v1' -d '{"url": "https://my-people.secure-url-location.org/network.json"}

WebSocket

websocket.send('{"command": "api_call", "method": "network_create", "kwargs": {"url": "https://my-people.secure-url-location.org/network.json"} }');

network_select(name)

Use this method to switch between different, previously loaded, network configurations. Only one network configuration can be active at a moment.

HTTP

curl -X POST 'localhost:8180/network/select/v1' -d '{"name": "my-people"}

WebSocket

websocket.send('{"command": "api_call", "method": "network_select", "kwargs": {"name": "my-people"} }');

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_disconnect()

This method will stop service_network() service. Your BitDust node will be completely disconnected from the currently selected peer-to-peer network.

HTTP

curl -X GET 'localhost:8180/network/disconnect/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "network_disconnect", "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_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": {} }');

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": {} }');

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, include_signature=False, generate_signature=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="", active=True, 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_state(key_id, active)

Set active/inactive state for the given key. If key was set to "inactive" state, certain parts of the software will not use it.

HTTP

curl -X POST 'localhost:8180/key/state/v1' -d '{"key_id": "abcd1234$alice@server-a.com", "active": false}'

WebSocket

websocket.send('{"command": "api_call", "method": "key_state", "kwargs": {"key_id": "abcd1234$alice@server-a.com", "active": false} }');

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, include_signature=False, timeout=30)

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=None)

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(force=False)

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 only.

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 all 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, publish_events=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).

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, publish_events=False)

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 inside of the UI application 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_info(key_id)

Returns detailed info about given shared location.

HTTP

curl -X GET 'localhost:8180/share/info/v1?key_id=share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com'

WebSocket

websocket.send('{"command": "api_call", "method": "share_info", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"} }');

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

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 stored inside 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=45, publish_events=True)

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, publish_events=False)

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 DELETE '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=30)

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_info_dht(group_creator_id)

Read and return list of message brokers stored in the corresponding DHT records for given user.

HTTP

curl -X GET 'localhost:8180/group/info/dht/v1?group_creator_id=alice@server-a.com'

WebSocket

websocket.send('{"command": "api_call", "method": "group_info_dht", "kwargs": {"group_creator_id": "alice@server-a.com"} }');

group_join(group_key_id, publish_events=False, use_dht_cache=True, wait_result=True)

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", "erase_key": 1}'

WebSocket

websocket.send('{"command": "api_call", "method": "group_leave", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "erase_key": 1} }');

group_reconnect(group_key_id, use_dht_cache=False)

Refreshing given messaging group - disconnect from the group first and then join again. Helpful method to reconnect with the group suppliers effectively.

HTTP

curl -X PUT 'localhost:8180/group/reconnect/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"}'

WebSocket

websocket.send('{"command": "api_call", "method": "group_reconnect", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"} }');

group_share(group_key_id, trusted_user_id, timeout=45, publish_events=False)

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 all 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/remove/v1' -d '{"user_id": "dave@device-d.gov"}'

WebSocket

websocket.send('{"command": "api_call", "method": "friend_remove", "kwargs": {"user_id": "dave@device-d.gov"} }');

user_ping(user_id, timeout=None, retries=1)

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=None)

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"} }');

user_search(nickname, attempts=1)

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: group_message, private_message, 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=15, 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: private_message, personal_message or group_message.

This method is only make sense for HTTP interface, because via a WebSocket it is possible to receive streamed messages instantly.

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 are holding each and every encrypted file created by you or file uploaded by other users that still belongs to you.

Your BitDust node also able to connect to suppliers employed by other users. It makes possible to upload and download a shared data. Information about those external suppliers is cached and can be also accessed 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_list_dht(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_list_dht", "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, erase_customer_key=True)

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, as_tree=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/[network name]/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/[network name]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"} }');

service_health(service_name)

Method will execute "health check" procedure of the given service - each service defines its own way to verify that.

HTTP

curl -X POST 'localhost:8180/service/health/service_message_history/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "service_health", "kwargs": {"service_name": "service_message_history"} }');

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 all 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 all 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 all registered queue producers.

HTTP

curl -X GET 'localhost:8180/queue/producer/list/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "queue_producers_list", "kwargs": {} }');

queue_keepers_list()

Returns list of all registered queue keepers.

HTTP

curl -X GET 'localhost:8180/queue/keeper/list/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "queue_keepers_list", "kwargs": {} }');

queue_peddlers_list()

Returns list of all registered message peddlers.

HTTP

curl -X GET 'localhost:8180/queue/peddler/list/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "queue_peddlers_list", "kwargs": {} }');

queue_streams_list()

Returns list of all registered message peddlers.

HTTP

curl -X GET 'localhost:8180/queue/stream/list/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "queue_streams_list", "kwargs": {} }');

events_list()

Returns an overall statistic of the all logged events since the start of the main process.

HTTP

curl -X GET 'localhost:8180/event/list/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "events_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'

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": {} }');

blockchain_info()

Returns details and brief info about current status of blockchain services.

HTTP

curl -X GET 'localhost:8180/blockchain/info/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "blockchain_info", "kwargs": {} }');

blockchain_wallet_balance()

Returns current balance of your blockchain wallet.

HTTP

curl -X GET 'localhost:8180/blockchain/wallet/balance/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "blockchain_wallet_balance", "kwargs": {} }');

blockchain_transaction_send(recipient, amount, operation="", data="")

Prepare and sign blockchain transaction and then send it to one of known blockchain nodes.

HTTP

curl -X POST 'localhost:8180/blockchain/transaction/send/v1' -d '{"recipient": "abcd...", "amount": "12.3456"}'

WebSocket

websocket.send('{"command": "api_call", "method": "blockchain_transaction_send", "kwargs": {"recipient": "abcd...", "amount": "12.3456"} }');

blockchain_block_produce()

Will trigger minining one time to produce a single empty block in the blockchain. This way foundation miners can initially generate enough coins to be able to sell those coins to customers.

This method only make sense to use by foundation miners. If you are not part of the foundation and your wallet address is not on the list, your transaction will be rejected by other nodes.

HTTP

curl -X GET 'localhost:8180/blockchain/block/produce/v1'

WebSocket

websocket.send('{"command": "api_call", "method": "blockchain_block_produce", "kwargs": {} }');

billing_info()

billing_offers_list()

billing_offer_create()

billing_bid_create()

billing_bid_accept()

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": {} }');

automat_info(index=None, automat_id=None)

Returns detailed info about given state machine.

Target instance is selected using one of the identifiers: index (integer) or automat_id (string).

HTTP

curl -X GET 'localhost:8180/automat/info/v1?index=12345'

WebSocket

websocket.send('{"command": "api_call", "method": "automat_info", "kwargs": {"index": 12345} }');

automat_events_start(index=None, automat_id=None, state_unchanged=False)

Can be used to capture any state machine updates in real-time: state transitions, incoming events.

Changes will be published as "events" and can be captured with event_listen() API method.

Positive value of parameter state_unchanged will enable all updates from the state machine - even when incoming automat event did not changed its state it will be published.

Target instance is selected using one of the identifiers: index (integer) or automat_id (string).

HTTP

curl -X POST 'localhost:8180/automat/events/start/v1' -d '{"index": 12345, "state_unchanged": 1}

WebSocket

websocket.send('{"command": "api_call", "method": "automat_events_start", "kwargs": {"index": 12345, "state_unchanged": 1} }');

automat_events_stop(index=None, automat_id=None)

Turn off publishing of the state machine updates as events.

Target instance is selected using one of the identifiers: index (integer) or automat_id (string).

HTTP

curl -X POST 'localhost:8180/automat/events/stop/v1' -d '{"index": 12345}

WebSocket

websocket.send('{"command": "api_call", "method": "automat_events_stop", "kwargs": {"index": 12345} }');

Beginning

Principles

Development

Repositories

API methods

BitDust API

Intro

HTTP Rest API

WebSocket

Command line shell client

Access

API methods

enable_model_listener(model_name, request_all=False)

WebSocket

disable_model_listener(model_name)

WebSocket

request_model_data(model_name, query_details=None)

WebSocket

process_stop(instant=True)

HTTP

WebSocket

process_restart()

HTTP

WebSocket

process_health()

HTTP

WebSocket

process_info()

HTTP

WebSocket

process_debug()

HTTP

WebSocket

devices_list(sort=False)

HTTP

WebSocket

device_info(name)

HTTP

WebSocket

device_add(name, routed=False, activate=True, wait_listening=False, web_socket_port=None, key_size=None)

HTTP

WebSocket

device_start(name, wait_listening=False)

HTTP

WebSocket

device_authorization_reset(name, start=True, wait_listening=False)

device_client_code_input(name, client_code)

device_stop(name)

HTTP

WebSocket

device_remove(name)

HTTP

WebSocket

network_create(url)

HTTP

WebSocket

network_select(name)

HTTP

WebSocket

network_connected(wait_timeout=5)

HTTP

WebSocket

network_disconnect()

HTTP

WebSocket

network_reconnect()

HTTP

WebSocket

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

HTTP

WebSocket

network_configuration()

HTTP

WebSocket

network_stun(udp_port=None, dht_port=None)

HTTP

WebSocket

config_get(key, include_info=False)

HTTP

WebSocket