Page tree
Skip to end of metadata
Go to start of metadata

 

Introduction

UAPI accesses the cPanel interface's features. Use this API to access and modify cPanel account data and settings.

Notes:

  • If you encounter problems with a local access method (LiveAPI PHP, LiveAPI Perl, or Template Toolkit), attempt a browser-based call.
  • 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

/execute/Module/function?parameter=value&parameter=value&parameter=value
$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',
         )
);

Note:

For more information, read our Guide to the LiveAPI System.

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',
    }
);

Note:

For more information, read our Guide to the LiveAPI System.

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

Note:

For more information, read our Guide to Template Toolkit documentation. 

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

Notes:

  • UAPI 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 Guide to UAPI - Return Data documentation.
  • cPanel & WHM introduced the command line feature in version 56.

UAPI calls through the command line consist of the following basic parts:

 

PartDescription
CommandThis value is always UAPI for calls to UAPI.
UserThe account-level username.
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.
  • Use --output=yaml to return YAML-formatted output.

Note:

This parameter defaults to --output=yaml.

ModuleThe UAPI module name.
FunctionThe UAPI function.
UserThe cPanel account username.
Input parameters and values

The function's input parameters and their values.

  • You must URI-encode values.
  • Separate multiple parameter=value pairs with a space character.
  • 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:
    • uapi --user username Module function key=[\"sslinstall\",\"videotut\"]"
    • uapi --user username Module function key='{"videotut","sslinstall"}'

Note:

The term "Boolean" in our documentation refers to parameters that accept values of 1 or 0. cPanel & WHM APIs do not support the literal values of true and false.

Note:

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

uapi --help

Note:

For more information about browser-based UAPI calls, read the cPanel or Webmail Session URL calls section below. 

This example uses the following variables:

VariableDescriptionPossible valuesExample
ModuleThe function's module.Any UAPI module.Email
functionThe UAPI function.Any UAPIfunctionin the specified module.addpop
parametersThe function's input parameters.

Any parameter from the specified function.

domain
valueThe value to assign to the input parameter.Parameters accept a variety of values.example.com

cPanel or Webmail Session URL calls

You can access UAPI functions directly from any web browser when you make the call from a cPanel or Webmail session.

Browser-based calls consist of the following basic parts:

PartDescription
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:

    • 2082 —Unsecure calls as a specific cPanel account.
    • 2083 — Secure calls as a specific cPanel account.
    • 2095 —Unsecure calls via a Webmail session.
    • 2096 — Secure calls via a Webmail session.

Warning:

Unless you call this API via the WHM API, you cannot call this API via WHM's ports (2086 or 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. 

ActionThis portion of the URL will always be execute.
ModuleThe UAPI module name.
FunctionThe UAPI function.
Input parameters and values

The UAPI 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 APIs do not support the literal values of true and false.

Warning:

Do not attempt to use the URL of a cPanel or WHM interface in order 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, Inc. 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
  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"
  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

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. 

 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.