Guide to WHM API 1

WHM API 1 accesses the WHM interface's features. You can use this API to perform server administration tasks, administrate cPanel and WHM reseller accounts, and manage cPanel & WHM services.

Important:

In cPanel & WHM version 76, we introduced server profiles and roles. When you enable a non-Standard Node server profile, the system disables API calls associated with that profile's disabled roles.

Notes:

Use the applist command to return an alphabetical list of WHM API 1 functions.
You cannot call this API's functions via another API's call methods. For more information, read the API method distinctions section below.

Basic usage

https://hostname.example.com:2087/cpsess##########/json-api/accountsummary?api.version=1&user=username

WHM API calls through JSON consist of the following basic parts:

Part	Description
Server and port	The web server's HTTP address and the port number to use. Generally, this value begins with `https://` and the domain name. When you call this API, use the following ports: `2086` — Unsecure calls as a specific WHM account. `2087` — Secure calls as a specific WHM account. Warning: You cannot call this API via cPanel ports (`2082` or `2083`) or Webmail ports (`2095` or `2096`).
Security token	The current session's security token. Note: Cookie-based calls (for example, calls from a web browser) require a security token. For other authentication methods, read our Guide to API Authentication documentation.
API type	The API output type that you wish to receive. Use `json-api` to return JSON-formatted output.
Function	The WHM API function.
API version	The API version to use. To call WHM API 1, set the `api.version` parameter to `1`. Important: If you do not include the API version, the call will default to WHM API 0.
Input parameters and values	The function's input parameters and their values. You must URI-encode these values. Separate multiple `parameter=value` pairs with the ampersand character (`&`). Note: The term "Boolean" in our documentation refers to parameters that accept values of `1` or `0`. cPanel & WHM's APIs do not support the literal values of `true` and `false`.

Important:

cPanel & WHM version 66 deprecated XML output for cPanel API 1, cPanel API 2, UAPI, WHM API 0, and WHM API 1.

Calls for XML API output will return a deprecation warning.
We plan to remove XML output entirely in a future version of cPanel & WHM.

For more information, read our cPanel Deprecation Plan documentation.

https://hostname.example.com:2087/cpsess##########/xml-api/accountsummary?api.version=1&user=username

Warning:

This API's XML output does not comply with XML standards, is slower than JSON output to produce, and may result in validation errors. We strongly recommend that you use JSON.

WHM API calls through XML consist of the following basic parts:

Part	Description
Server and port	The web server's HTTP address and the port number to access. Generally, this value begins with `https://` and the domain name. For secure calls to the WHM API, the port is always `2087`.
Security token	The current session's security token. Note: Cookie-based calls (for example, calls from a web browser) require a security token. For other authentication methods, read our Guide to API Authentication documentation.
API type	The API output type that you wish to receive. Use `xml-api` to return XML-formatted output.
Function	The WHM API function.
API version	The API version to use. To call WHM API 1, set the `api.version` parameter to `1`. Important: If you do not include the API version, the call will default to WHM API 0.
Input parameters and values	The function's input parameters and their values. Separate multiple `parameter=value` pairs with the ampersand character (`&`). You must URI-encode these values. Note: The term "Boolean" in our documentation refers to parameters that accept values of `1` or `0`. cPanel & WHM's APIs do not support the literal values of `true` and `false`.

whmapi1 accountsummary user=username

Notes:

cPanel & WHM introduced the command line feature in version 11.52.0.8.
WHM API 1 calls via the command line do not return the metadata that other methods return if they experience errors that prevent a successful function run. For more information, read our WHM API 1 - Return Data documentation.

WHM API calls through the command line consist of the following basic parts:

Part	Description
Command	This value is always `whmapi1` for calls to WHM API 1. Note: If you run CloudLinux™, you must use the full path of the `whmapi1` command: /usr/local/cpanel/bin/whmapi1
Output Type	The API output type that you wish to receive. Use `--output=json` to return JSON-formatted output. Use `--output=jsonpretty` to return indented JSON-formatted output. Use `--output=xml` to return XML-formatted output. Important: cPanel & WHM version 66 deprecated XML output. Use `--output=yaml` to return YAML-formatted output. Note: This parameter defaults to `--output=yaml`.
Function	The WHM API function.
Input parameters and values	The function's input parameters and their values. Separate multiple `parameter=value` pairs with a space character. You must URI-encode values. Special characters within a key's value may cause an error. You must either escape any special characters within values or surround the value with appropriate quotes. For more information, read Wikipedia's Escape Characters article. For example, a bash shell command with a JSON-encoded value may appear similar to one of the following: `whmapi1 function key=[\"sslinstall\",\"videotut\"]"` `whmapi1 function key='{"videotut","sslinstall"}'` Note: The term "Boolean" in our documentation refers to parameters that accept values of `1` or `0`. cPanel & WHM's APIs do not support the literal values of `true` and `false`.

Note:

For more information about this feature, run the following command:

whmapi1 --help

Warning:

Do not attempt to use cPanel or WHM interface URLs to perform actions in custom code. You must call the appropriate API functions in order to perform the actions of cPanel & WHM's interfaces.

For example, do not pass values to .html pages, as in the following example:

http://example.com:2082/frontend/x3/mail/doaddpop.html/email=name&domain=user.com

While this unsupported method sometimes worked in previous versions of cPanel & WHM, we strongly discourage its use and do not guarantee that it will work in the future. Instead, the correct method to perform this action is to call the appropriate API function.

API method distinctions

cPanel, L.L.C. produces four current and two deprecated APIs, and they all include separate sets of functions. Make certain that the function and module that you call exist in the API version that your code uses.

Important:

API calls must use the correct port:

2082 — Unsecure calls to cPanel's APIs.
2083 — Secure calls to cPanel's APIs.
2095 — Unsecure calls to cPanel's APIs via a Webmail session.
2096 — Secure calls to cPanel's APIs via a Webmail session.
2086 — Unsecure calls to WHM's APIs, or to cPanel's APIs via the WHM API.
2087 — Secure calls to WHM's APIs, or to cPanel's APIs via the WHM API.

Otherwise-correct calls will return Permission denied or Function not found errors if they use an incorrect port number.

Select a tab to view examples of calls to the desired API:

Browser-based call...

https://hostname.example.com:2087/cpsess##########/json-api/accountsummary?api.version=1&user=username

Note:

Browser-based calls to WHM API 1 must include the WHM API version (api.version=1). If you omit the version, the system calls WHM API 0, which may not contain the desired function, or may contain an older version of that function.

Command-line call...

whmapi1 accountsummary user=username

For more information, read our Guide to Testing Custom Code - WHM API Calls and Guide to WHM API 1 documentation.

cPanel or Webmail session URL call...

https://hostname.example.com:2083/cpsess##########/execute/Module/function?parameter=value&parameter=value&parameter=value

Command-line call...

uapi --user=username --output=type Module function parameter=value parameter=value

LiveAPI PHP Class call...

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// Call a UAPI function.
$function_result = $cpanel->uapi(
    'Module', 'function',
    array(
        'parameter'     => 'value',
        'parameter'     => 'value',
        'parameter'     => 'value',
         )
);

LiveAPI Perl Module call...

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Call a UAPI function.
my $function_result = $cpliveapi->uapi(
    'Module', 'function',
    {
        'parameter'     => 'value',
        'parameter'     => 'value',
        'parameter'     => 'value',
    }
);

Template Toolkit call...

<!-- Call a UAPI function. -->
[% 
execute( 
     'Module', 'function', 
     { 
        'parameter' => 'value', 
        'parameter' => 'value', 
        'parameter' => 'value', 
     } 
); 
%]

Note:

For more information, read our Guide to Testing Custom Code - cPanel API and UAPI Calls and Guide to UAPI documentation.

Call through the WHM API...

https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Module&cpanel_jsonapi_func=function&parameter="value"

Command-line call...

cpapi2 --user=username --output=type Module function parameter=value parameter=value

Template Toolkit call...

<!-- Call a cPanel API 2 function. -->
[%- 
USE Api2;
SET myvariable = execute( 
     'Module', 'function',
    {
        'parameter'      => 'value',
        'parameter'      => 'value',
        'parameter'      => 'value',
    }
);
%]

LiveAPI PHP Class call...

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
   
// Call the function.
$my_variable = $cpanel->api2(
    'Module', 'function',
    array(
        'parameter'      => 'value', 
        'parameter'      => 'value', 
        'parameter'      => 'value',
    )
 );

LiveAPI Perl Module call...

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Call the function.
my $my_variable = $cpliveapi->api2(
    'Module', 'function',
    {
        'parameter'      => 'value',
        'parameter'      => 'value',
        'parameter'      => 'value',
    }
);

Note:

For more information, read our Guide to Testing Custom Code - cPanel API and UAPI Calls and Guide to cPanel API 2 documentation.

Warning:

WHM API 0 is deprecated. We strongly recommend that you only use the equivalent WHM API 1 functions instead.

Browser-based call...

https://hostname.example.com:2087/cpsess##########/json-api/accountsummary?user=username

Command-line call...

whmapi0 accountsummary user=username

Note:

For more information, read our Guide to Testing Custom Code - WHM API Calls and Guide to WHM API 0 documentation.

Warning:

cPanel API 1 is deprecated. We strongly recommend that you use cPanel API 2 or UAPI instead.

Command-line call...

cpapi1 --user=username --output=type Module function parameter=value parameter=value

LiveAPI PHP Class call...

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
$your_variable = $cpanel->api1('Module', 'function', array('parameter', 'parameter', 'parameter') ); // Call the function.

LiveAPI Perl Module call...

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
my $your_variable = $cpliveapi->api1('Module', 'function', ['parameter', 'parameter', 'parameter'] ); # Call the function.

Template Toolkit call...

<!-- Call a cPanel API 1 function. -->
[%- 
USE Api1;
SET myvariable = execute( 
     'Module', 'function',
    {
        'parameter'      => 'value',
        'parameter'      => 'value',
        'parameter'      => 'value',
    }
);
%]

Note:

For more information, read our Guide to Testing Custom Code - cPanel API and UAPI Calls and Guide to cPanel API 1 documentation.

WHM API 1 Basics

Available in:

WHM 11+

Languages:

JSON, XML

Methods:

GET, POST

Return Formats:

JSON, XML

Important:

cPanel & WHM version 66 deprecated XML output.

About WHM API 1

WHM API 1 performs functions and accesses data in WHM.

Notes:

Some functions and parameters may require that you authenticate as the root user.
You must use the appropriate WHM ports (2086 or 2087) to call WHM API functions.

Child pages

Introduction

Basic usage

API method distinctions

WHM API 1 Basics

About WHM API 1

Related Documentation