Introduction to UAPI

Overview

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

• If you encounter problems with a local access method (LiveAPI PHP or LiveAPI Perl), attempt a browser-based call .
• You cannot call this API's functions via another API's call methods.
• When you enable a non-Standard Node server profile , the system disables API calls associated with that profile's disabled roles.

Basic Usage

cPanel or Webmail Session URL

/execute/Module/function?parameter=value&parameter=value&parameter=value

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:

LiveAPI PHP Class

$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 - PHP Class .
• For more information about browser-based UAPI calls, read the cPanel or Webmail Session URL calls below.

This example uses the following variables:

LiveAPI Perl Class

#!/usr/bin/perl

# Instantiate the Cpanel::LiveAPI object.
use Cpanel::LiveAPI ();

# Connect to cPanel - only do this once.
my $cpliveapi = Cpanel::LiveAPI->new();

# Call a UAPI function.
my $function_result = $cpliveapi->uapi(
    'Module', 'function',
    {
        'parameter'     => 'value',
        'parameter'     => 'value',
        'parameter'     => 'value',
    }
);

# Perform the desired actions.

# Disconnect from cPanel - only do this once.
$cpliveapi->end();

Note

• For more information, read our Guide to the LiveAPI System - Perl Module .
• For more information about browser-based UAPI calls, read the cPanel or Webmail Session URL calls below.

This example uses the following variables:

Command Line

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

Note

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

Command

This value is always uapi for calls to UAPI. If you run CloudLinux™, you must use the full path of the uapi command:/usr/local/cpanel/bin/uapi

User

The 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=yaml to return YAML-formatted output.

This parameter defaults to --output=yaml.

Module

The UAPI module name.

Function

The UAPI function.

User

The cPanel account username.

Input parameters and values

The function's input parameters and their values.

• Space-separate multiple parameter=value pairs.
• 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 examples:

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

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

uapi --help

cPanel or Webmail Session URL

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:

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 1, 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.

Action

This portion of the URL will always be execute.

Module

The UAPI module name.

Function

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

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.