API development status

Is the API developed or it was just an early idea and the development stopped? In the documentation it seems incomplete but there is no warning that is in alpha or beta, just few examples and no documentation on the API itself.

The API it self is stable and running since initial release. Unless you mean a 3rd party api?

1 Like

In case it is useful to you, I’ve created a wrapper bash script for Hestia API.

I’ve also documented how to create the diferrent keys for new and legacy API, how to add an external ip to Allowed IPs so you can use the ip from another machine, etc.

v-wrapper-hestia-api

This is an utility to interact with Hestia API. It is a bash script that uses curl to perform the API calls and you just need to add the command you want to use and its arguments as parameters.

Install:

With git clone

cd ~
git clone https://github.com/sahsanu/v-wrapper-hestia-api.git
sudo cp v-wrapper-hestia-api/v-wrapper-hestia-api /usr/local/bin/

With curl

sudo curl -s https://raw.githubusercontent.com/sahsanu/v-wrapper-hestia-api/main/v-wrapper-hestia-api -o /usr/local/bin/v-wrapper-hestia-api
sudo chmod 755 /usr/local/bin/v-wrapper-hestia-api

With wget

sudo wget https://raw.githubusercontent.com/sahsanu/v-wrapper-hestia-api/main/v-wrapper-hestia-api -O /usr/local/bin/v-wrapper-hestia-api
sudo chmod 755 /usr/local/bin/v-wrapper-hestia-api

Configure options to be used by the script (host, port and credentials):

Create and edit file ~/.v-wrapper-hestia-api.conf

For New API add the following variables with your own data:

host='hestiacp.example.com'
port='8083'
access_key='HereYourAccessKey'
secret_key='HereYourSecretKey'

For Legacy API (user/password) add the following variables with your own data (user will be always admin):

host='hestiacp.example.com'
port='8083'
user='admin'
password='HereYourPassword'

For Legacy API (hash) add the following variables with your own data:

host='hestiacp.example.com'
port='8083'
hash='HereYourHash'

For ALL API modes you can add all the variables and the script will use the correct ones depending on the options that have been used:

host='hestiacp.example.com'
port='8083'
access_key='HereYourAccessKey'
secret_key='HereYourSecretKey'
user='admin'
password='HereYourPassword'
hash='HereYourHash'

Usage:

v-wrapper-hestia-api [-l|--list] [-u|--user-password] [-h|--hash] HESTIA_COMMAND [ARG1] [ARG2] [...] [ARG13]

List Hestia commands:

With this option you can list the commands, descriptions and options used by Hestia.

v-wrapper-hestia-api [-l|--list] [search pattern]

Examples:

v-wrapper-hestia-api -l
v-wrapper-hestia-api -l v-change
v-wrapper-hestia-api --list v-list
v-wrapper-hestia-api -l '.*mail'
v-wrapper-hestia-api --list 'v-.*web'

Example output:

$ v-wrapper-hestia-api -l v-change-mail                                                                                   
HESTIA COMMAND                    DESCRIPTION                        OPTIONS
--------------                    -----------                        -------
v-change-mail-account-password    change mail account password       USER DOMAIN ACCOUNT PASSWORD
v-change-mail-account-quota       change mail account quota          USER DOMAIN ACCOUNT QUOTA
v-change-mail-account-rate-limit  change mail account rate limit     USER DOMAIN ACCOUNT RATE
v-change-mail-domain-catchall     change mail domain catchall email  USER DOMAIN EMAIL
v-change-mail-domain-rate-limit   change mail domain rate limit      USER DOMAIN RATE
v-change-mail-domain-sslcert      change domain ssl certificate      USER DOMAIN SSL_DIR [RESTART]

New API:

v-wrapper-hestia-api hestia_command [arg1] [arg2] [...] [arg13]

Legacy API (user/password):

v-wrapper-hestia-api [-u|--user-password] hestia_command [arg1] [arg2] [...] [arg13]

Legacy API (hash):

v-wrapper-hestia-api [-h|--hash] hestia_command [arg1] [arg2] [...] [arg13]

Examples:

v-wrapper-hestia-api v-list-users
v-wrapper-hestia-api v-list-web-domain user domain
v-wrapper-hestia-api -h v-list-web-domain user domain
v-wrapper-hestia-api --user-password v-list-users

Editing connection params:

You can edit the following variables inside the script:

v_host=''
v_port=''
v_access_key=''
v_secret_key=''
v_user=''
v_password=''
v_hash=''

Or you can create a config file .v-wrapper-hestia-api.conf in your $HOME or a file .v-wrapper-hestia-api.conf in the current dir (this one takes precedence over the other options).

If using a conf file, the variables to be used are (keep in mind that v- prefix is not used in conf file):

host=''
port=''
access_key=''
secret_key=''
user=''
password=''
hash=''

Note: By default, the script (in this case curl) needs a valid certificate installed in your Hestia Server, if your certificate is expired, self-signed, etc. you can ignore the certificate validation editing the script and changing variable curl_ignore_cert=0 to curl_ignore_cert=1 or add curl_ignore_cert=1 to your conf file.

How to create credentials in Hestia Control Panel to access API

New API

You can use Web UI to create an access key.

User admin profileAccess KeysAdd Access KeySelect the permissions you want to use and put a comment (without spaces)Save

You will see the new Access Key and the Secret Key (save both in a safe place).

Using command line you can create the access and secret keys using command v-add-access-key.

Usage: v-add-access-key USER [PERMISSIONS] [COMMENT] [FORMAT]

For example:

# v-add-access-key admin billing AdminBill
ACCESS_KEY_ID:      InNqgp01kO3v0W22eg6Z
SECRET_ACCESS_KEY:  lcp45pvgZh0f_33veMB2P6HDVUYpYeHjTatZ=hDu
USER:               admin
PERMISSIONS:        billing
COMMENT:            AdminBill
TIME:               01:35:44
DATE:               2023-09-10

If you want to view the apis available and the commands you could use in every api, use command v-list-apis.

# v-list-apis
API                 ROLE   COMMANDS
---                 ----   --------
billing             admin  v-add-user,v-delete-user,v-suspend-user,v-unsuspend-user,v-change-user-shell,v-list-user,v-list-users,v-make-tmp-file,v-add-domain,v-change-user-package,v-make-tmp-file,v-change-user-password
mail-accounts       user   v-list-mail-domains,v-list-mail-domain,v-list-mail-account,v-list-mail-accounts,v-list-mail-account-autoreply,v-delete-mail-account,v-delete-mail-account-alias,v-delete-mail-account-autoreply,v-delete-mail-account-forward,v-delete-mail-account-fwd-only,v-add-mail-account,v-add-mail-account-alias,v-add-mail-account-autoreply,v-add-mail-account-forward,v-add-mail-account-fwd-only,v-change-mail-account-password,v-change-mail-account-quota,v-suspend-mail-account,v-suspend-mail-accounts,v-unsuspend-mail-account,v-unsuspend-mail-accounts
phpmyadmin-sso      admin  v-add-database-temp-user,v-delete-database-temp-user
purge-nginx-cache   user   v-purge-nginx-cache,v-list-web-domains,v-list-web-domain
sync-dns-cluster    admin  v-list-users,v-list-sys-config,v-list-user,v-add-cron-restart-job,v-delete-dns-domains-src,v-insert-dns-domain,v-insert-dns-record,v-insert-dns-records,v-rebuild-dns-domains,v-rebuild-dns-domain,v-delete-dns-record,v-make-tmp-file,v-insert-dns-domain,v-delete-dns-domain
update-dns-records  user   v-list-dns-records,v-change-dns-record

You can modify existing apis or create your own one editing file in /usr/local/hestia/data/api/ or adding a file with the list of commands you want to use.

If for some reason you need to be able to use all available commands, you can give to admin user all permissions using this command (GodMode is just a funny comment), here, the important part is ''.

# v-add-access-key admin '' GodMode
ACCESS_KEY_ID:      ss7zCZQ5HasP3FeZyhYW
SECRET_ACCESS_KEY:  ircw1YhKzPlGufaNrQnutN8UOo3JkHqXvWKxCa3J
USER:               admin
PERMISSIONS:
COMMENT:            GodMode
TIME:               01:52:16
DATE:               2023-09-10

Legacy API (user/password)

Warning: Legacy API is not recommended and could be removed from Hestia in a future release.

You don’t need to create anything, just use your user admin (is the only user allowed) and its password. Using this method, you will be able to use all Hestia commands.

Legacy API (hash)

Warning: Legacy API is not recommended and could be removed from Hestia in a future release.

To create the hash you must use command line and command v-generate-api-key

Example:

# v-generate-api-key
zIafmk4i6opgjto7x3U_t8sVKj3JT6-P

Copy it and you are ready to use it. Using this method, you will be able to use all Hestia commands.

Add your client ip to allowed ips to access API

By default, Hestia doesn’t allow any ip to connect to API so if you want to connect from an external client, you must add your client ip to API_ALLOWED_IP.

Using Web UI: Server SettingsConfigureSecuritySystemAllowed IP addresses for APIAdd your client ip in a new lineSave

Using command line: v-add-sys-api-ip HereYourClientIp

I don’t recommend this but, if for some reason you want to allow all external ips to use your Hestia API, you can add the ip 0.0.0.0 via Web UI or via command line. Use at your own risk

Cheers,
sahsanu

1 Like

In the docs it seems incomplete API | Hestia Control Panel

I didn’t had the chance to test it but maybe it’s just a matter of using the API with the commands that are documented in the CLI?

We have moved all the examples to a Github repo for readability

How ever it doesn’t mean that the API is self is not working .

Also more information regarding the API can be found here:

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.