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)
Register a new API device configuration to be able to access this BitDust node remotely.
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_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} }');