XML and JSON APIs

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.

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.

Note: The JSON API is only available in cPanel/WHM version 11.25 and later.

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

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

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

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

JSON output format

Note: The JSON API is only available in cPanel/WHM version 11.25 and later.

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

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

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. This function is only available in WHM 11.25 and later.

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, including addon and subdomains, whether CGI aliasing is enabled, log locations, and other details. This function is only available in WHM 11.25 and later.

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. This function is only available in WHM 11.25 and later.

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. This function is only available in WHM 11.25 and later.

Edit a Zone Record (editzonerecord) — This function allows you to edit an existing zone record. This function is only available in WHM 11.25 and later.

Get a Zone Record (getzonerecord) — This function allows you to view DNS zone records associated with a given domain. This function is only available in WHM 11.25 and later.

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. This function is only available in WHM 11.25 and later.

Reset a DNS Zone (resetzone) — This API function will reset a DNS zone to its default values. This function is only available in WHM 11.25 and later.

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.

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.

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. This function is only available in WHM 11.25 and later.

Set Reseller Limits (setresellerlimits) — This function lets you set limits on the amount of bandwidth and disk space a reseller can use. This function is only available in WHM 11.25 and later.

Set up a Reseller's Main IP Address (setresellermainip) — This function lets you assign a main, shared IP address to a reseller's account. This function is only available in WHM 11.25 and later.

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. This function is only available in WHM 11.25 and later.

Suspend a Reseller's Account (suspendreseller) — This function lets you suspend a reseller, thereby preventing the reseller from accessing his or her account. This function is only available in WHM 11.25 and later.

Unsuspend a Reseller's Account (unsuspendreseller) — This function lets you unsuspend a reseller, thereby allowing the reseller to access his or her account. This function is only available in WHM 11.25 and later.

View Information about Accounts Owned by a Reseller (acctcounts) — This function lists the number of accounts owned by each reseller on the server. This function is only available in WHM 11.25 and later.

Set a Reseller's Nameservers (setresellernameservers) — This function allows you to define a reseller's nameservers. This function is only available in WHM 11.25 and later.

Server information

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

Display cPanel and 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.

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.

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.

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. This function is only available in WHM 11.25 and later.

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. This function is only available in WHM 11.25 and later.

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.

Resources

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

• XML API Mailing List
• cPanel Developer Forum