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.
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"
}
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 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
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.
You can find bellow a list of all API methods available at the moment.
Stop the main process immediately.
curl -X GET 'localhost:8180/process/stop/v1'
websocket.send('{"command": "api_call", "method": "process_stop", "kwargs": {} }');
Restart the main process.
curl -X GET 'localhost:8180/process/restart/v1'
websocket.send('{"command": "api_call", "method": "process_restart", "kwargs": {} }');
Returns positive response if engine process is running. This method suppose to be used for health checks.
curl -X GET 'localhost:8180/process/health/v1'
websocket.send('{"command": "api_call", "method": "process_health", "kwargs": {} }');
Returns overall information about current process. This method can be used for live monitoring and statistics.
curl -X GET 'localhost:8180/process/info/v1'
websocket.send('{"command": "api_call", "method": "process_info", "kwargs": {} }');
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.
curl -X GET 'localhost:8180/process/debug/v1'
websocket.send('{"command": "api_call", "method": "process_debug", "kwargs": {} }');
Returns current key/value from the program settings.
curl -X GET 'localhost:8180/config/get/v1?key=logs/debug-level'
websocket.send('{"command": "api_call", "method": "config_get", "kwargs": {"key": "logs/debug-level"} }');
Set a value for given key option.
curl -X POST 'localhost:8180/config/set/v1' -d '{"key": "logs/debug-level", "value": 12}'
websocket.send('{"command": "api_call", "method": "config_set", "kwargs": {"key": "logs/debug-level", "value": 12} }');
Provide detailed info about all program settings.
curl -X GET 'localhost:8180/config/list/v1'
websocket.send('{"command": "api_call", "method": "configs_list", "kwargs": {} }');
Returns all options as a tree structure, can be more suitable for UI operations.
curl -X GET 'localhost:8180/config/tree/v1'
websocket.send('{"command": "api_call", "method": "configs_tree", "kwargs": {} }');
Returns your identity info.
curl -X GET 'localhost:8180/identity/get/v1'
websocket.send('{"command": "api_call", "method": "identity_get", "kwargs": {} }');
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.
curl -X POST 'localhost:8180/identity/create/v1' -d '{"username": "alice", "join_network": 1}'
websocket.send('{"command": "api_call", "method": "identity_create", "kwargs": {"username": "alice", "join_network": 1} }');
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.
curl -X POST 'localhost:8180/identity/backup/v1' -d '{"destination_filepath": "/tmp/alice_backup.key"}'
websocket.send('{"command": "api_call", "method": "identity_backup", "kwargs": {"destination_filepath": "/tmp/alice_backup.key"} }');
Restores your identity from backup copy.
Input parameter private_key_source must contain your latest IDURL and the private key as openssh formated string.
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.send('{"command": "api_call", "method": "identity_recover", "kwargs": {"private_key_source": "http://some-host.com/alice.xml\n-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKC..."} }');
Method will erase current identity file and the private key (optionally). All network services will be stopped first.
curl -X DELETE 'localhost:8180/identity/erase/v1' -d '{"erase_private_key": true}'
websocket.send('{"command": "api_call", "method": "identity_erase", "kwargs": {"erase_private_key": true} }');
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.
curl -X PUT 'localhost:8180/identity/rotate/v1'
websocket.send('{"command": "api_call", "method": "identity_rotate", "kwargs": {} }');
Returns list of all cached locally identity files received from other users.
curl -X GET 'localhost:8180/identity/cache/list/v1'
websocket.send('{"command": "api_call", "method": "identity_cache_list", "kwargs": {} }');
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.
curl -X GET 'localhost:8180/key/get/v1?key_id=abcd1234$alice@server-a.com'
websocket.send('{"command": "api_call", "method": "key_get", "kwargs": {"key_id": "abcd1234$alice@server-a.com"} }');
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.
curl -X GET 'localhost:8180/key/list/v1?include_private=1'
websocket.send('{"command": "api_call", "method": "keys_list", "kwargs": {"include_private": 1} }');
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.
curl -X POST 'localhost:8180/key/create/v1' -d '{"key_alias": "abcd1234", "key_size": 1024, "label": "Cats and Dogs"}'
websocket.send('{"command": "api_call", "method": "key_create", "kwargs": {"key_alias": "abcd1234", "key_size": 1024, "label": "Cats and Dogs"} }');
Set new label for the given key.
curl -X POST 'localhost:8180/key/label/v1' -d '{"key_id": "abcd1234$alice@server-a.com", "label": "Man and Woman"}'
websocket.send('{"command": "api_call", "method": "key_label", "kwargs": {"key_id": "abcd1234$alice@server-a.com", "label": "Man and Woman"} }');
Unregister and remove given key from the list of known keys and erase local file.
curl -X DELETE 'localhost:8180/key/erase/v1' -d '{"key_id": "abcd1234$alice@server-a.com"}'
websocket.send('{"command": "api_call", "method": "key_erase", "kwargs": {"key_id": "abcd1234$alice@server-a.com"} }');
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.
curl -X PUT 'localhost:8180/key/share/v1' -d '{"key_id": "abcd1234$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"}'
websocket.send('{"command": "api_call", "method": "key_share", "kwargs": {"key_id": "abcd1234$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"} }');
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.
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.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} }');
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.
curl -X GET 'localhost:8180/file/sync/v1'
websocket.send('{"command": "api_call", "method": "files_sync", "kwargs": {} }');
files_list(remote_path=None, key_id=None, recursive=True, all_customers=False, include_uploads=False, include_downloads=False)
Returns list of known files registered in the catalog under given remote_path folder.
By default returns items from root of the catalog.
If key_id is passed will only return items encrypted using that key.
Use all_customers=True to get list of all registered files - including received/shared to you by another user.
You can also use include_uploads and include_downloads parameters to get more info about currently running
uploads and downloads.
curl -X GET 'localhost:8180/file/list/v1?remote_path=abcd1234$alice@server-a.com:pictures/cats/'
websocket.send('{"command": "api_call", "method": "files_list", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:pictures/cats/"} }');
Returns positive result if file or folder with such remote_path already exists in the catalog.
curl -X GET 'localhost:8180/file/exists/v1?remote_path=abcd1234$alice@server-a.com:pictures/cats/pussy.png'
websocket.send('{"command": "api_call", "method": "file_exists", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:pictures/cats/pussy.png"} }');
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.
curl -X GET 'localhost:8180/file/info/v1?remote_path=abcd1234$alice@server-a.com:pictures/dogs/bobby.jpeg'
websocket.send('{"command": "api_call", "method": "file_info", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:pictures/dogs/bobby.jpeg"} }');
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.
curl -X POST 'localhost:8180/file/create/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:movies/travels/safari.mp4"}'
websocket.send('{"command": "api_call", "method": "file_create", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:movies/travels/safari.mp4"} }');
Removes virtual file or folder from the catalog and also notifies your remote suppliers to clean up corresponding uploaded data.
curl -X POST 'localhost:8180/file/delete/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:cars/ferrari.gif"}'
websocket.send('{"command": "api_call", "method": "file_delete", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/ferrari.gif"} }');
Returns a list of currently running uploads and list of pending items to be uploaded.
curl -X GET 'localhost:8180/file/upload/v1'
websocket.send('{"command": "api_call", "method": "files_uploads", "kwargs": {} }');
Starts a new file or folder (including all sub-folders and files) upload from local_path on your disk drive
to the virtual location remote_path in the catalog. New "version" of the data will be created for given catalog item
and uploading task started.
You can use wait_result=True to block the response from that method until uploading finishes or fails (makes no sense for large uploads).
Parameter open_share can be useful if you uploading data into a "shared" virtual path using another key that shared to you.
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.send('{"command": "api_call", "method": "file_upload_start", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg", "local_path": "/tmp/fiat.jpeg"} }');
Useful method if you need to interrupt and cancel already running uploading task.
curl -X POST 'localhost:8180/file/upload/stop/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"}'
websocket.send('{"command": "api_call", "method": "file_upload_stop", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"} }');
Returns a list of currently running downloading tasks.
curl -X GET 'localhost:8180/file/download/v1'
websocket.send('{"command": "api_call", "method": "files_downloads", "kwargs": {} }');
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!
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.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/"} }');
Abort currently running restore process.
curl -X POST 'localhost:8180/file/download/stop/v1' -d '{"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"}'
websocket.send('{"command": "api_call", "method": "file_download_stop", "kwargs": {"remote_path": "abcd1234$alice@server-a.com:cars/fiat.jpeg"} }');
Useful method to be executed from the UI right after downloading is finished.
It will open default OS file manager and display
given local_path to the user so he can do something with the file.
curl -X GET 'localhost:8180/file/explore/v1?local_path=/tmp/movies/back_to_the_future.mp4'
websocket.send('{"command": "api_call", "method": "file_explore", "kwargs": {"local_path": "/tmp/movies/back_to_the_future.mp4"} }');
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.
curl -X GET 'localhost:8180/share/list/v1?only_active=1'
websocket.send('{"command": "api_call", "method": "shares_list", "kwargs": {"only_active": 1} }');
Creates a new "share" - virtual location where you or other users can upload/download files.
This method generates a new RSA private key that will be used to encrypt and decrypt files belongs to that share.
By default you are the owner of the new share and uploaded files will be stored by your suppliers.
You can also use owner_id parameter if you wish to set another owner for that new share location.
In that case files will be stored not on your suppliers but on his/her suppliers, if another user authorized the share.
Optional input parameter key_size can be 1024, 2048, 4096. If key_size was not passed, default value will be
populated from the personal/private-key-size program setting.
Parameter label can be used to attach some meaningful information about that share location.
curl -X POST 'localhost:8180/share/create/v1' -d '{"label": "my summer holidays"}'
websocket.send('{"command": "api_call", "method": "share_create", "kwargs": {"label": "my summer holidays"} }');
Stop the active share identified by the key_id and erase the private key.
curl -X DELETE 'localhost:8180/share/delete/v1' -d '{"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"}'
websocket.send('{"command": "api_call", "method": "share_delete", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"} }');
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.
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.send('{"command": "api_call", "method": "share_grant", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"} }');
Activates given share and initiate required connections to remote suppliers to make possible to upload and download shared files.
curl -X PUT 'localhost:8180/share/open/v1' -d '{"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"}'
websocket.send('{"command": "api_call", "method": "share_open", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"} }');
Disconnects and deactivate given share location.
curl -X PUT 'localhost:8180/share/close/v1' -d '{"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"}'
websocket.send('{"command": "api_call", "method": "share_close", "kwargs": {"key_id": "share_7e9726e2dccf9ebe6077070e98e78082$alice@server-a.com"} }');
Method is not implemented yet.
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.
curl -X GET 'localhost:8180/group/list/v1'
websocket.send('{"command": "api_call", "method": "groups_list", "kwargs": {} }');
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.
curl -X POST 'localhost:8180/group/create/v1' -d '{"label": "chat with my friends"}'
websocket.send('{"command": "api_call", "method": "group_create", "kwargs": {"label": "chat with my friends"} }');
Returns detailed info about the message group identified by group_key_id.
curl -X GET 'localhost:8180/group/info/v1?group_key_id=group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com'
websocket.send('{"command": "api_call", "method": "group_info", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"} }');
Activates given messaging group to be able to receive streamed messages or send a new message to the group.
curl -X POST 'localhost:8180/group/join/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"}'
websocket.send('{"command": "api_call", "method": "group_join", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"} }');
Deactivates given messaging group. If erase_key=True will also erase the private key related to that group.
curl -X DELETE 'localhost:8180/group/leave/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"}'
websocket.send('{"command": "api_call", "method": "group_leave", "kwargs": {"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com"} }');
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.
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.send('{"command": "api_call", "method": "group_share", "kwargs": {"key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "trusted_user_id": "bob@machine-b.net"} }');
Returns list of registered correspondents.
curl -X GET 'localhost:8180/friend/list/v1'
websocket.send('{"command": "api_call", "method": "friends_list", "kwargs": {} }');
Add user to the list of correspondents.
You can attach an alias to that user as a label to be displayed in the UI.
curl -X POST 'localhost:8180/friend/add/v1' -d '{"trusted_user_id": "dave@device-d.gov", "alias": "SuperMario"}'
websocket.send('{"command": "api_call", "method": "friend_add", "kwargs": {"trusted_user_id": "dave@device-d.gov", "alias": "SuperMario"} }');
Removes given user from the list of correspondents.
curl -X DELETE 'localhost:8180/friend/add/v1' -d '{"user_id": "dave@device-d.gov"}'
websocket.send('{"command": "api_call", "method": "friend_add", "kwargs": {"user_id": "dave@device-d.gov"} }');
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).
curl -X GET 'localhost:8180/user/ping/v1?user_id=carol@computer-c.net'
websocket.send('{"command": "api_call", "method": "suppliers_ping", "kwargs": {} }');
Returns short info about current on-line status of the given user.
curl -X GET 'localhost:8180/user/status/v1?user_id=carol@computer-c.net'
websocket.send('{"command": "api_call", "method": "user_status", "kwargs": {"user_id": "carol@computer-c.net"} }');
Returns current online status of a user and only if node is known but disconnected performs "ping" operation.
curl -X GET 'localhost:8180/user/status/check/v1?user_id=carol@computer-c.net'
websocket.send('{"command": "api_call", "method": "user_status_check", "kwargs": {"user_id": "carol@computer-c.net"} }');
Doing lookup of a single nickname registered in the DHT network.
curl -X GET 'localhost:8180/user/search/v1?nickname=carol'
websocket.send('{"command": "api_call", "method": "user_search", "kwargs": {"nickname": "carol"} }');
Reads all records registered for given nickname in the DHT network.
It could be that multiple users chosen same nickname when creating an identity.
curl -X GET 'localhost:8180/user/observe/v1?nickname=carol'
websocket.send('{"command": "api_call", "method": "user_observe", "kwargs": {"nickname": "carol"} }');
Returns chat history stored during communications with given user or messaging group.
curl -X GET 'localhost:8180/message/history/v1?message_type=group_message&recipient_id=group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com'
websocket.send('{"command": "api_call", "method": "message_history", "kwargs": {"recipient_id" : "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "message_type": "group_message"} }');
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.
curl -X POST 'localhost:8180/message/send/v1' -d '{"recipient_id": "carlos@computer-c.net", "data": {"message": "Hola Amigo!"}}'
websocket.send('{"command": "api_call", "method": "message_send", "kwargs": {"recipient_id": "carlos@computer-c.net", "data": {"message": "Hola Amigos!"}} }');
Sends a "group_message" to a group of users.
Input data must be a JSON dictionary.
curl -X POST 'localhost:8180/message/send/group/v1' -d '{"group_key_id": "group_95d0fedc46308e2254477fcb96364af9$alice@server-a.com", "data": {"message": "Hola Amigos!"}}'
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" or "group_message".
This method is only make sense for HTTP interface, because using a WebSocket client will receive streamed message directly.
curl -X GET 'localhost:8180/message/receive/my-client-group-messages/v1?message_types=group_message'
This method returns a list of your suppliers. Those nodes stores your encrypted file or file uploaded by other users that still belongs to you.
Your BitDust node also sometimes need to connect to suppliers of other users to upload or download shared data.
Those external suppliers lists are cached and can be selected here with customer_id optional parameter.
curl -X GET 'localhost:8180/supplier/list/v1'
websocket.send('{"command": "api_call", "method": "suppliers_list", "kwargs": {} }');
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.
curl -X POST 'localhost:8180/supplier/change/v1' -d '{"position": 1, "new_supplier_id": "carol@computer-c.net"}'
websocket.send('{"command": "api_call", "method": "supplier_change", "kwargs": {"position": 1, "new_supplier_id": "carol@computer-c.net"} }');
Sends short requests to all suppliers to verify current connection status.
curl -X POST 'localhost:8180/supplier/ping/v1'
websocket.send('{"command": "api_call", "method": "suppliers_ping", "kwargs": {} }');
Scans DHT network for key-value pairs related to given customer and returns a list its suppliers.
curl -X GET 'localhost:8180/supplier/list/dht/v1?customer_id=alice@server-a.com'
websocket.send('{"command": "api_call", "method": "suppliers_dht_lookup", "kwargs": {"customer_id": "alice@server-a.com"} }');
Method returns list of your customers - nodes for whom you are storing data on that host.
curl -X GET 'localhost:8180/customer/list/v1'
websocket.send('{"command": "api_call", "method": "customers_list", "kwargs": {} }');
Stop supporting given customer, remove all related files from local disc, close connections with that node.
curl -X DELETE 'localhost:8180/customer/reject/v1' -d '{"customer_id": "dave@device-d.gov"}'
websocket.send('{"command": "api_call", "method": "customer_reject", "kwargs": {"customer_id": "dave@device-d.gov"} }');
Check current on-line status of all customers.
curl -X POST 'localhost:8180/customer/ping/v1'
websocket.send('{"command": "api_call", "method": "customers_ping", "kwargs": {} }');
Returns detailed info about quotas and usage of the storage space you donated to your customers.
curl -X GET 'localhost:8180/space/donated/v1'
websocket.send('{"command": "api_call", "method": "space_donated", "kwargs": {} }');
Returns info about current usage of the storage space provided by your suppliers.
curl -X GET 'localhost:8180/space/consumed/v1'
websocket.send('{"command": "api_call", "method": "space_consumed", "kwargs": {} }');
Returns info about current usage of your local disk drive.
curl -X GET 'localhost:8180/space/local/v1'
websocket.send('{"command": "api_call", "method": "space_local", "kwargs": {} }');
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.
curl -X GET 'localhost:8180/service/list/v1?with_configs=1'
websocket.send('{"command": "api_call", "method": "services_list", "kwargs": {"with_configs": 1} }');
Returns detailed info about single service.
curl -X GET 'localhost:8180/service/info/service_private_groups/v1'
websocket.send('{"command": "api_call", "method": "service_info", "kwargs": {"service_name": "service_private_groups"} }');
Starts given service immediately.
This method also set True for correspondent option in the program settings to mark the service as enabled:
.bitdust/config/services/[service name]/enabled
Other dependent services, if they were enabled before but stopped, also will be started.
curl -X POST 'localhost:8180/service/start/service_supplier/v1'
websocket.send('{"command": "api_call", "method": "service_start", "kwargs": {"service_name": "service_supplier"} }');
Stop given service immediately.
This method also set False for correspondent option in the program settings to mark the service as disabled:
.bitdust/config/services/[service name]/enabled
Dependent services will be stopped as well but will not be disabled.
curl -X POST 'localhost:8180/service/stop/service_supplier/v1'
websocket.send('{"command": "api_call", "method": "service_stop", "kwargs": {"service_name": "service_supplier"} }');
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.
curl -X POST 'localhost:8180/service/restart/service_customer/v1'
websocket.send('{"command": "api_call", "method": "service_restart", "kwargs": {"service_name": "service_customer"} }');
Returns list of incoming and outgoing signed packets running at the moment.
curl -X GET 'localhost:8180/packet/list/v1'
websocket.send('{"command": "api_call", "method": "packets_list", "kwargs": {} }');
Returns detailed info about overall network usage.
curl -X GET 'localhost:8180/packet/stats/v1'
websocket.send('{"command": "api_call", "method": "packets_stats", "kwargs": {} }');
Returns list of current data fragments transfers to/from suppliers.
curl -X GET 'localhost:8180/transfer/list/v1'
websocket.send('{"command": "api_call", "method": "transfers_list", "kwargs": {} }');
Returns list of opened/active network connections.
Argument protocols can be used to select which protocols to be present in the response:
curl -X GET 'localhost:8180/connection/list/v1?protocols=tcp,udp,proxy'
websocket.send('{"command": "api_call", "method": "connections_list", "kwargs": {"protocols": ["tcp", "udp", "proxy"]} }');
Returns list of running streams of data fragments with recent upload/download progress percentage.
curl -X GET 'localhost:8180/stream/list/v1'
websocket.send('{"command": "api_call", "method": "streams_list", "kwargs": {} }');
Returns list of registered streaming queues.
curl -X GET 'localhost:8180/queue/list/v1'
websocket.send('{"command": "api_call", "method": "queues_list", "kwargs": {} }');
Returns list of registered queue consumers.
curl -X GET 'localhost:8180/queue/consumer/list/v1'
websocket.send('{"command": "api_call", "method": "queue_consumers_list", "kwargs": {} }');
Returns list of registered queue producers.
curl -X GET 'localhost:8180/queue/producer/list/v1'
websocket.send('{"command": "api_call", "method": "queue_producers_list", "kwargs": {} }');
Method will generate and inject a new event inside the main process.
This method is provided for testing and development purposes.
curl -X POST 'localhost:8180/event/send/client-event-abc/v1' -d '{"data": {"some_key": "some_value"}}'
websocket.send('{"command": "api_call", "method": "event_send", "kwargs": {"event_id": "client-event-produced", "data": {"some_key": "some_value"}} }');
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.
curl -X GET 'localhost:8180/event/listen/my-client-event-hook/v1'
Begins network STUN process to detect your network configuration and current external IP address of that host.
curl -X GET 'localhost:8180/network/stun/v1'
websocket.send('{"command": "api_call", "method": "network_stun", "kwargs": {} }');
Method can be used to refresh network status and restart all internal connections.
curl -X GET 'localhost:8180/network/reconnect/v1'
websocket.send('{"command": "api_call", "method": "network_reconnect", "kwargs": {} }');
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.
curl -X GET 'localhost:8180/network/connected/v1'
websocket.send('{"command": "api_call", "method": "network_connected", "kwargs": {} }');
network_status(suppliers=False, customers=False, cache=False, tcp=False, udp=False, proxy=False, dht=False)
Returns detailed info about current network status, protocols and active connections.
curl -X GET 'localhost:8180/network/status/v1?cache=1&suppliers=1&dht=1'
websocket.send('{"command": "api_call", "method": "network_status", "kwargs": {"cache": 1, "suppliers": 1, "dht": 1} }');
Returns details about network services.
curl -X GET 'localhost:8180/network/configuration/v1'
websocket.send('{"command": "api_call", "method": "network_configuration", "kwargs": {} }');
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.
curl -X GET 'localhost:8180/dht/node/find/v1?node_id_64=4271c8f079695d77f80186ac9365e3df949ff74d'
websocket.send('{"command": "api_call", "method": "dht_node_find", "kwargs": {"node_id_64": "4271c8f079695d77f80186ac9365e3df949ff74d"} }');
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.
curl -X GET 'localhost:8180/dht/user/random/v1?count=2&layer_id=2'
websocket.send('{"command": "api_call", "method": "dht_node_find", "kwargs": {"count": 2, "layer_id": 2} }');
Fetch single key/value record from DHT network.
curl -X GET 'localhost:8180/dht/value/get/v1?key=abcd'
websocket.send('{"command": "api_call", "method": "dht_value_get", "kwargs": {"key": "abcd"} }');
Writes given key/value record into DHT network. Input parameter value must be a JSON value.
curl -X POST 'localhost:8180/dht/value/set/v1' -d '{"key": "abcd", "value": {"text": "A-B-C-D"}}'
websocket.send('{"command": "api_call", "method": "dht_value_set", "kwargs": {"key": "abcd", "value": {"text": "A-B-C-D"}} }');
Method used for testing purposes, returns full list of all key/values stored locally on that DHT node.
curl -X GET 'localhost:8180/dht/db/dump/v1'
websocket.send('{"command": "api_call", "method": "dht_local_db_dump", "kwargs": {} }');
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.
curl -X GET 'localhost:8180/automat/list/v1'
websocket.send('{"command": "api_call", "method": "automats_list", "kwargs": {} }');