Skip to content
On this page

REST API

The Hestia REST API is available to perform core functions of the Control Panel. For example, we use it internally to synchronise DNS clusters and to integrate the WHMCS billing system. The API can also be used to create new user accounts, domains, databases or even to build an alternative web interface.

The API reference provides PHP code samples demonstrating how you can integrate the API into your application or script. However, you also can use any other language to communicate with the API.

With the release of Hestia v1.6.0, we have introduced a more advanced API system and it will allow non-admin users to use specific commands.

I’m unable to connect to the API

With the release of Hestia v1.4.0, we have decided the security needed to be tightened. If you want to connect to the API from a remote server, you will first need to whitelist its IP address. To add multiple addresses, separate them with a new line.

Can I disable the API?

Yes, you can disable the API via the server settings. The file will be deleted from the server and all connections will get ignored. Please note that some functions may not work with the API disabled.

Password vs API key vs access keys

Password

  • Should only be used by the admin user.
  • Changing the admin password requires updating it everywhere it’s used.
  • Allowed to run all commands.

API key

  • Should only be used by the admin user.
  • Changing the admin password does not have consequences.
  • Allowed to run all commands.

Access keys

  • User-specific.
  • Can limit permissions. For example only v-purge-nginx-cache.
  • Ability to disable login via other methods but still allow the use of api keys
  • Can be restricted to admin user only or allowed for all users.

Setup access/secret key authentication

To create an access key, follow the guide in our documentation.

If the software you are using already supports the hash format, use ACCESS_KEY:SECRET_KEY instead of your old API key.

Create an API key

WARNING

This method has been replaced by the above access/secret key authentication. We highly recommend using this more secure method instead.

Run the command v-generate-api-key.

Return codes

ValueNameComment
0OKCommand has been successfully performed
1E_ARGSNot enough arguments provided
2E_INVALIDObject or argument is not valid
3E_NOTEXISTObject doesn’t exist
4E_EXISTSObject already exists
5E_SUSPENDEDObject is already suspended
6E_UNSUSPENDEDObject is already unsuspended
7E_INUSEObject can’t be deleted because it is used by another object
8E_LIMITObject cannot be created because of hosting package limits
9E_PASSWORDWrong / Invalid password
10E_FORBIDENObject cannot be accessed by this user
11E_DISABLEDSubsystem is disabled
12E_PARSINGConfiguration is broken
13E_DISKNot enough disk space to complete the action
14E_LAServer is to busy to complete the action
15E_CONNECTConnection failed. Host is unreachable
16E_FTPFTP server is not responding
17E_DBDatabase server is not responding
18E_RDDRRDtool failed to update the database
19E_UPDATEUpdate operation failed
20E_RESTARTService restart failed

Released under the GPLv3 License.