Our XML API allows you to issue commands to cPanel and WHM using the XML language, while our JSON API allows you to submit requests to the system and receive a JSON response. By including these commands in your custom scripts, you can perform functions remotely, without having to access the cPanel or WHM user interface.

There are several possible applications of the XML and JSON APIs. For example, they can make managing a data center easy by allowing you to issue a single command across multiple servers.

For information about parsing XML output, visit our Parsing XML document.

Important: The JSON API is much less resource-intensive than the XML API. We highly recommend using the JSON API, especially if performance is important, since it provides much faster results.

Formatting and using API calls

Each XML and JSON API call is formatted as a URL. To create a function call:

Begin with the HTTP address of your web server.

Append a colon (:) and the appropriate port number. The port you use will vary depending on whether you wish to issue a command to WHM or cPanel.
- 2082 — cPanel (unsecured).
- 2083 — cPanel (secured).
- 2086 — WHM (unsecured).
- 2087 — WHM (secured).

Add /xml-api/functionname or /json-api/functionname, plus any variables required by the specific function you are calling. (For more information, see the documentation for each function, linked below.)

For example, if your web server's hostname is example.com, you would include one of the following strings in your script:
- https://example.com:2087/xml-api/functionname
- https://example.com:2087/json-api/functionname

You need to be logged in with the proper permissions in order to call a function. See our document about Authenticating API Function Calls for more information about authenticating APIs from within a script.

You can also perform the function by entering the string in your web browser's address bar. This may be useful for testing the function call and viewing its output.

Examples

To use the setupreseller function on a server whose hostname is example.com, you would include a string similar to the following in your script:

XML API: https://example.com:2087/xml-api/setupreseller?user=bob&makeowner=1
JSON API: https://example.com:2087/json-api/setupreseller?user=bob&makeowner=1

Variables used in XML and JSON function calls

In addition to the input and output variables detailed here, each function call has its own distinct variables and output. For complete information about the function you wish to use, see the list of API functions below.

Input

A function call consists of the following input variables:

name (string) — Name of the XML or JSON API call.
? — A question mark (?) is used to append information to the call.
variable=value (string) — Variables and their values can then be passed to the call.
& — An ampersand (&) is used to add variables and values to the call.

XML output format

Show Hide

The output consists of a call container, in angle brackets (<>), that contains a result container, also in angle brackets (<>). The output will appear like so:

For calls which perform an action

<name_of_XMLAPI_call>
     <result (status of the request) />
</name_of_XML_API_call>

For calls which only request data

<name_of_XMLAPI_call>
     <item (information about the item) /> 
     ("Item" is the item request, such as a package, account, etc.)
</name_of_XML_API_call>

Example

Calling this URL in WebHost Manager: /xml-api/setupreseller?user=bob&makeowner=1 will produce XML similar to:

<setupreseller>
     <result status="1" statusmsg=""/>
</setupreseller>

JSON output format

Show Hide

For calls which perform an action

{
   "result":[
      {
         "status":1,
         "statusmsg":null
      }
   ]
}

For calls which only request data

{
   "status":1,
   "statusmsg":"Ok",
   "acct":[
      {
         "Item":"Parameters/Results",
         "Next Item":"Parameters/Results"
      },
      {
         "Item":"Parameters/Results",
         "Next Item":"Parameters/Results"
      }
   ]
}

Example

Calling this URL in WebHost Manager: /json-api/setupreseller?user=bob&makeowner=1 will produce JSON output similar to:

{
   "result":[
      {
         "status":1,
         "statusmsg":null
      }
   ]
}

How to batch function calls

You can combine multiple API version 1 calls with the batch function.

For example, you can combine the gethostname and version function calls with the following:

http://example.com:2087/SESSIONID/xml-api/batch?api.version=1&command=gethostname&command=version

This will provide the following output:

Show Hide

<result>
    <data>
        <result>
            <data>
                <hostname>hostname.example.com</hostname>
            </data>
            <metadata>
                <version>1</version>
                <reason>OK</reason>
                <result>1</result>
                <command>gethostname</command>
            </metadata>
        </result>
        <result>
            <data>
                <version>11.38.0.6</version>
            </data>
            <metadata>
                <version>1</version>
                <reason>OK</reason>
                <result>1</result>
                <command>version</command>
            </metadata>
        </result>
    </data>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>batch</command>
    </metadata>
</result>

The following is the same batch function call in JSON format:

{
  "data": {
    "result": [
      {
        "data": {
          "hostname": "hostname.example.com"
        },
        "metadata": {
          "version": 1,
          "reason": "OK",
          "result": 1,
          "command": "gethostname"
        }
      },
      {
        "data": {
          "version": "11.38.0.6"
        },
        "metadata": {
          "version": 1,
          "reason": "OK",
          "result": 1,
          "command": "version"
        }
      }
    ]
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": 1,
    "command": "batch"
  }
}

If the function call takes arguments, you will need to format the input as URI (Uniform Resource Identifier) encoding.

For example, you can add the killdns function call to the earlier example:

http://example.com:2087/SESSIONID/xml-api/batch?api.version=1&command=gethostname&command=version&command=killdns%3Fdomain%3Dexample.com%0A=

Functions

List Available API Calls (applist) — This function lists all XML/JSON API functions available to you.

Call the cPanel API1 and API2 commands (cpanel) — You can use the XML and JSON APIs to access cPanel API versions 1 and 2.

Account functions

Create an Account (createacct) — This API function allows you to create new cPanel accounts.

Change an Account's Password (passwd) — Using this API function, you can change a cPanel account's password.

Limit Bandwidth Usage (Transfer) (limitbw) — This API function allows you to change bandwidth limits for cPanel accounts.

List Accounts (listaccts) — This API function will generate a list of accounts associated with a server.

Modify an Account (modifyacct) — Using this API function, you are able to change specific attributes of cPanel accounts, such as the theme or domain.

Edit Quota (editquota) — This API function allows you to edit a user's disk space quota.

Show an Account's Information (accountsummary) — This API function will generate a list of an account's attributes, such as its IP address and partition.

Suspend an Account (suspendacct) — Using this API function, you can prevent a user from accessing his or her cPanel account.

List Suspended Accounts (listsuspended) — This function allows you to view a list of suspended accounts on your server.

Terminate an Account (removeacct) — This API function allows you permanently remove an account from a server.

Unsuspend an Account (unsuspendacct) — Using this API function, you can allow a user to access his or her cPanel account after it has been suspended.

Upgrade or Downgrade an Account (changepackage) — This API function allows you to change the hosting plan associated with a cPanel account.

View Current User's Privileges (myprivs) — Using this API function, you can find out what privileges you have within WHM.

Obtain User Data for a Domain (domainuserdata) — This function displays information about a given domain. This information includes whether or not CGI aliasing is enabled, log locations, and other details.

Change a Site's (or User's) IP Address (setsiteip) — This function allows you to change the IP address associated with a website, or a user's account, hosted on your server.

Restore an Account Backup (restoreaccount) — This function allows you to restore a backup for an account. You may restore daily, weekly, or monthly backups. This function is only available in version 11.28+.

Set Digest Authentication (set_digest_auth) — This function enables or disables Digest Authentication for a user account. Windows® Vista, Windows® 7, and Windows® 8 require Digest Authentication support be enabled in order to access the Web Disk over a clear text, unencrypted connection. This function is only available in version 11.34+.

Has Digest Authentication (has_digest_auth) — This function will check whether a cPanel user has digest authentication enabled. Windows® Vista, Windows® 7, and Windows® 8 require Digest Authentication support be enabled in order to access the Web Disk over a clear text, unencrypted connection. This function is only available in version 11.34+.

Restore Queue Add Task (restore_queue_add_task) — This function allows you to restore a user's account from a backup file. This function is only available in version 11.38+.

Restore Queue Activate (restore_queue_activate) — This function allows you to activate the restore queue and trigger a process to restore all queued accounts. This function is only available in version 11.38+.

Restore Queue Is Active (restore_queue_is_active) — This function allows you to see if the queue is actively processing restore jobs. This function is only available in version 11.38+.

Restore Queue List Pending (restore_queue_list_pending) — This function allows you to list all queued accounts to be restored. This function is only available in version 11.38+.

Restore Queue List Active (restore_queue_list_active) — This function allows you to list all accounts currently being restored. This function is only available in version 11.38+.

Restore Queue List Completed (restore_queue_list_completed) — This function allows you to list all completed restorations along with the success or failure of the restore and the restore log. This function is only available in version 11.38+.

Restore Queue Clear Pending Task (restore_queue_clear_pending_task) — This function allows you to clear a single pending account from the Restoration Queue. This function is only available in version 11.38+.

Restore Queue Clear All Pending Tasks (restore_queue_clear_all_pending_tasks) — This function allows you to clear all pending accounts from the Restore Queue. This function is only available in version 11.38+.

Restore Queue Clear Completed Task (restore_queue_clear_completed_task) — This function allows you to clear a single, completed account from the Restoration Queue. This function is only available in version 11.38+.

Restore Queue Clear All Completed Tasks (restore_queue_clear_all_completed_tasks) — This function allows you to clear all successfully completed tasks from the Restoration Queue. This function is only available in version 11.38+.

Restore Queue Clear All Failed Tasks (restore_queue_clear_all_failed_tasks) — This function allows you to clear all failed tasks from the Restoration Queue. This function is only available in version 11.38+.

Restore Queue Clear All Tasks (restore_queue_clear_all_tasks) — This function allows you to clear the Restoration Queue of all jobs, no matter the status. This function is only available in version 11.38+.

Backup Config Get (backup_config_get) — This function allows you to receive detailed data from your backup destination config file. This function is only available in version 11.38+.

Backup Config Set (backup_config_set) — This function allows you to save the data from the backup config page and put the data in /var/cpanel/backups/config This function is only available in version 11.38+.

Backup Skip Users All (backup_skip_users_all) — This function allows you to save the configuration for a given backup type. You can enable or disable backups all users. This function is only available in version 11.38+.

Backup Skip Users All Status (backup_skip_users_all_status) — This function allows you to retrieve the value from the status log file in the backup_skip_users_all api call. This function is only available in version 11.38+.

Backup Set List (backup_set_list) — This function allows you to find all backup files available on the server. This function also returns a list of users and dates so that the Restore Account(s) feature in WHM can show them. This function is only available in version 11.38+.

Backup Date List (backup_date_list) — This function allows you to retrieve a list of all dates that have backups. This function is only available in version 11.38+.

Backup User List (backup_user_list) — This function allows you to list all users with a backup file on a specific date. This function is only available in version 11.38+.

Backup Destination Validate (backup_destination_validate) — This function allows you to run a validation routine on a specified backup destination. This function is only available in version 11.38+.

Backup Destination Add (backup_destination_add) — This function allows you to create a backup destination and save it to a config file. This function is only available in version 11.38+.

Backup Destination Set (backup_destination_set) — This function allows you to modify the setup and data for a backup destination. The information is saved to the config file of the backup destination. This function is only available in version 11.38+.

Backup Destination Delete (backup_destination_delete) — This function allows you to remove the backup destination config file. This function is only available in version 11.38+.

Backup Destination Get (backup_destination_get) — This function allows you to retrieve detailed data for a specific backup destination from the backup destination config file. This function is only available in version 11.38+.

Backup Destination List (backup_destination_list) — This function allows you to list all backup destinations, including their configuration information. This function is only available in version 11.38+.

DNS functions

Note: If you wish to change the IP in a zone record, you may find the swapip script more suitable than an API function.

Add a DNS Zone (adddns) — This API function lets you create a DNS zone.

Add a Zone Record (addzonerecord) — This API function allows you to add a zone record.

Add a Reverse DNS Zone Record (addzonerecord) — You can use the addzonerecord function to add a reverse DNS zone record.

Edit a Zone Record (editzonerecord) — This function allows you to edit an existing zone record.

Get a Zone Record (getzonerecord) — This function allows you to view DNS zone records associated with a given domain.

Delete a DNS Zone (killdns) — This API function lets you delete a DNS zone.

List All DNS Zones (listzones) — This API function lists all domains and DNS zones on your server.

List (Dump) 1 Zone (dumpzone) — This API function displays the DNS zone configuration for a specific domain.

Look up a Nameserver's IP Address (lookupnsip) — This API function retrives the IP address of a registered nameserver.

Remove a DNS Zone Record (removezonerecord) — This function allows you to remove a zone record from the server.

Reset a DNS Zone (resetzone) — This API function will reset a DNS zone to its default values.

Resolve an IP Address from a Domain (resolvedomainname) — This function allows you to resolve the IP address of a specified domain. This function is only available in version 11.28+.

List a Domain's MX Records (listmxs) — This function will retrieve a list of a domain's MX records. This function is only available in version 11.28+.

Create a new MX Record (savemxs) — This function allows you to create a new MX record. This function is only available in version 11.28+.

Package functions

Add a Package (addpkg) — This API function adds a hosting package to your server.

Delete a Package (killpkg) — This API function deletes a hosting package from your server.

Edit a Package (editpkg) — This function lets you edit aspects of a hosting package.

List Packages (listpkgs) — This API function lets you view all hosting packages available to the user.

List Available Features (getfeaturelist) — This function lists available features that you can assign to packages. This function is only available in version 11.28+.

Reseller functions

Add Reseller Privileges (setupreseller) — This function allows you to confer reseller status to a user's account.

Create a Reseller ACL List (saveacllist) — This function allows you to create a new ACL list to use when setting up reseller accounts.

List Current Reseller ACL Lists (listacls) — This function lists the saved reseller ACL lists on the server.

List Reseller Accounts (listresellers) — This function lists all resellers on the server.

List Reseller's Accounts' Information (resellerstats) — This function shows statistics for a specific reseller's accounts.

Get Reseller IPs (getresellerips) — This function will retrieve a list of IP Addresses that are available to a specified reseller.

Remove Reseller Privileges (unsetupreseller) — This function removes reseller status from a user's account.

Set a Reseller's ACL List (setacls) — This function specifies the ACL for a reseller, or modifies specific ACL features for a reseller.

Terminate a Reseller (terminatereseller) — This function allows you to terminate a reseller's account.

Assign a Reseller IP Addresses (setresellerips) — This function lets you add IP addresses to a reseller's account.

Set Reseller Limits (setresellerlimits) — This function lets you set limits on the amount of bandwidth and disk space a reseller can use.

Set up a Reseller's Main IP Address (setresellermainip) — This function lets you assign a main, shared IP address to a reseller's account.

Define a Reseller's Packages (setresellerpackagelimit) — This function allows you to control which packages resellers are able to use. It also lets you define the number of times a package can be used by a reseller.

Suspend a Reseller's Account (suspendreseller) — This function lets you suspend a reseller, thereby preventing the reseller from accessing his or her account.

Unsuspend a Reseller's Account (unsuspendreseller) — This function lets you unsuspend a reseller, thereby allowing the reseller to access his or her account.

View Information about Accounts Owned by a Reseller (acctcounts) — This function lists the number of accounts owned by each reseller on the server.

Set a Reseller's Nameservers (setresellernameservers) — This function allows you to define a reseller's nameservers.

Server information

Display Server Hostname (gethostname) — This function displays the server's hostname.

Display cPanel & WHM Version (version) — This function displays the version of cPanel & WHM running on the server.

Display the Server's Load Average (loadavg) — This function displays your server's load average.

Display the Server's Load Average (with Metadata) (systemloadavg) — This function displays your server's load average along with the call's metadata. This function is only available in version 11.28+.

View a List of Available Languages (getlanglist) — This function displays a list of the languages available on your server.

Server administration

Note: If you wish to change the IP in a DNS zone record, you may find the swapip script more suitable than an API function.

Reboot the Server (reboot) — This function allows you to restart your server.

Add IP Address (addip) — This function allows you to add an IP address to your server in API version 0.

Add IP Address (addips) — This function allows you to add an IP address to your server in API version 1.

Delete IP Address (delip) — This function allows you to delete an IP address from your server.

List IP Addresses (listips) — This function allows you to list IP addresses associated with your server.

Set Hostname (sethostname) — This function allows you to set the hostname for your server. Note: This name must be different from your domain name.

Set Resolvers (setresolvers) — This function allows you to set the resolvers your server will use.

Show Bandwidth (showbw) — This function will list bandwidth usage per account.

Set a Non-Volatile Variable Value (nvset) — Non-volatile variables are used to save data on your server. This function allows you to set a non-volatile variable's value.

Retrieve a Non-Volatile Variable Value (nvget) — This function allows you to retrieve and view a non-volatile variable's value.

Set Tier (set_tier) — This function will set your server to the specified support tier.

Generate or Retrieve an Access Hash (accesshash) — This function allows you to retrieve an access hash for the root user. This function is only available in version 11.32+.

Retrieve Documentation about a Specified Key (fetch_doc_key) — This function call allows you to retrieve documentation about a key referenced within a specified module. This function is only available in version 11.32+.

Validate Exim's Configuration File Syntax (validate_exim_configuration_syntax) — This function will evaluate and validate Exim configuration file syntax. This function is only available in version 11.32+.

Validate the Current Exim Configuration (validate_current_installed_exim_config) — This function validates the system's current Exim configuration. This function is only available in version 11.32+.

Check and Repair the Exim Configuration (exim_configuration_check) — This function will check and, if it encounters any errors, attempt to repair your Exim configuration. This function is only available in version 11.32+.

Remove Exim Dry Run Configuration Files (remove_in_progress_exim_config_edit) — This function allows you to remove dry run files after a failed Exim update attempt. This function is only available in version 11.32+.

Retrieve a Tweak Settings option's value (get_tweaksetting) — You can use this function to retrieve the value of an option available on the WHM Tweak Settings screen. This function is only available in version 11.32+.

Set a Tweak Settings option's value (set_tweaksetting) — You can use this function to change the value of an option available on the WHM Tweak Settings screen. This function is only available in version 11.32+.

Retrieve Delivery Records (emailtrack_search) — This function retrieves delivery records. This function can return a large amount of data. You should filter and paginate results. This function is only available in version 11.32+.

Get Available Tiers (get_available_tiers) — This function will retrieve a list of all available support tiers of cPanel and WHM.

Set cPanel Updates (setcpanelupdates) — This function will set the frequency that updates will run on the server.

Service functions

Restart Service (restartservice) — This function lets you restart a service, or daemon, on your server.

Service Status (servicestatus) — This function tells you which services (daemons) are enabled, installed, and monitored on your server.

Configure a Service (configureservice) — This function allows you to enable or disable a service, and enable or disable monitoring of that service, as in the WHM Service Manager.

SSL functions

Fetch SSL Certificate Information (fetchsslinfo) — This function displays an SSL certificate, CA bundle, and private key for a specified domain, or it can display a CA bundle and private key for a specified SSL certificate.

Generate an SSL Certificate (generatessl) — This function generates an SSL certificate.

Install an SSL Certificate (installssl) — This function lets you install an SSL certificate onto the server.

List Available SSL Certificates (listcrts) — This function lists all domains on the server which have SSL certificates installed.

Set the Primary Domain (set_primary_servername) — This function allows WHM users to set the primary domain on an IP address and port type for their accounts' sites. This function is only available in version 11.38+.

Check for SNI Support (is_sni_supported) — This function allows WHM users to see if the server supports SNI, which allows for multiple SSL certificates per IP address and port number. This function is only available in version 11.38+.

Service SSL functions

Install a Certificate on a Service (

install_service_ssl_certificate) — This function allows WHM users to install a new certificate on a service. These services are =ftp

, exim, dovecot, courier, and cpanel. This function is only available in version 11.38+.

Reset a Certificate on a Service (reset_service_ssl_certificate) — This function allows WHM users to regenerate a self-signed certificate and assign the certificate to a service. These services are ftp, exim, dovecot, courier, and cpanel. This function is only available in version 11.38+.

Retrieve a List of Services and Corresponding Certificates (fetch_service_ssl_components) — This function allows WHM users to retrieve a list of services and their corresponding certificates. These services are ftp, exim, dovecot, courier, and cpanel. This function is only available in version 11.38+.

Resources

These resources can help you interact with the XML and JSON APIs:

cPanel Developer Forum

Topic revision: r64 - 17 Jun 2013 - 15:22:15 - Main.LaurenceSimon