< All Topics

API Basics

Posted
Updated

SPanel uses a REST API, which relies on POST related requests and JSON formatted responses from the API endpoint.
All API requests are performed on the API endpoint located inside SPanel’s directory.

https://IP_or_HOSTNAME/spanel/api.php

Warning
The API endpoint is dependant on the branding url settings, so the name of the folder is subject to change to ‘hostpanel’ or ‘spanel’ (default) if the owner of the VM enables that feature from the admin interface.

Authentication

Authentication is performed using an API token generated from the SPanel Admin Interface. The API token is provided with the rest of the request inside the ‘token’ variable. Tokens can be Admin or Client based tokens, depending on how they are generated.

Admin based tokens have access to the functionality available inside the SPanel Admin interface. Requests to the API, which use an admin token should not provide the ‘accountuser’ field.

Client based tokens are generated with a client username and are limited to performing SPanel Client interface actions only for the username with which they are generated. On the time of authentication to the SPanel API, the account username is provided in the ‘accountuser’ field.

FieldTypeRequiredDescription
tokenstringYesAuth token generated from SPanel Admin Interface
accountuserstringNoAccount user if the token is user-specific

Parameters

Request calls require 1 additional parameters, ‘action’. It is dependant on the type of the token/user combination and is different for Admin and Client calls. Additional parameters might be required depending on the function executed. More info can be found in each function’s article.

FieldTypeRequiredDescription
actionstringYesThe category and function being executed
accountuserstringYes/NoThe accountuser parameter is required only when executing user functions. It contains the SPanel user account name to which the function will be performed.

Example

$endpointUrl = 'https://123.123.123.123/spanel/api.php';
$postData = [
  'token' => 'provided_auth_token',
  'accountuser' => 'username',
  'action' => 'accounts/listaccounts',
];

$ch = curl_init();
curl_setopt( $ch, CURLOPT_URL, $endpointUrl);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt( $ch, CURLOPT_POST, true);
curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt( $ch, CURLOPT_SSL_VERIFYHOST, false);
$jsonOutput = curl_exec( $ch );

Output

Success

The above request will provide the following json output:

{
   "data":[
      {
         "domain":"testdomain.com",
         "user":"testuser",
         "ip":"123.123.123.123",
         "disk":"123",
         "inodes":"123",
         "homedir":"home",
         "numaddons":"0",
         "numsubdomains":"0",
         "numdatabases":"0",
         "numemails":"0",
         "numftpaccts":"0",
         "suspended":"0",
         "disklimit":"Unlimited",
         "inodeslimit":"Unlimited",
         "domainslimit":"Unlimited",
         "emailslimit":"Unlimited",
         "databaseslimit":"Unlimited",
         "setupDate":"01.10.2021",
         "package":"Custom"
      }
   ]
}

Error

Output errors always have a standard format, providing an array of error fields with the descriptive text provided for the corresponding issue.

{
   "result": "error",
   "message":[
      {
         "error1":"Descriptive error message for error1",
         "error2":"Descriptive error message for error2"
      }
   ]
}
Table of Contents