cPanel XML and JSON APIs — cpanel

Under certain circumstances, you may need to use the XML or JSON API as a "wrapper" to access the functions performed by API version 1 or version 2. You can do this from within either WebHost Manager or cPanel.

Using the XML and JSON APIs to call API1 and API2 functions

To use the XML or JSON API to access API1 and API2 functions from within your custom script:

• Append /xml-api/cpanel or /json-api/cpanel, plus the required variables (see below), to a URL which includes the address of your server.

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

Warning: API1 can return HTML-embedded within XML or JSON. This can causes parsing errors within most XML parsers. API2 functions should always be used in favor of API1 functions when possible.

Note: If you use a cPanel port (2082 or 2083) to access the XML or JSON API, you can only use it to run API1 and API2 functions. Native XML and JSON API calls will not work. The ports are assigned as follows:

• 2082 — cPanel (unsecured).
• 2083 — cPanel (secured).
• 2086 — WHM (unsecured).
• 2087 — WHM (secured).

Fast Mode

Fast Mode is a newer way to use the cpanel function call in the XML or JSON API. This method is preferred, since it simplifies building the request, no longer requiring you to enter XML tags as input. The server-side processing of Fast Mode requests is also much quicker than the processing of XML requests.

Variables

XML Input

The cpanel XML function call in Fast Mode takes the following variables as input.

The following variables are required:

• cpanel_xmlapi_user (string) — The user as whom you wish to call the function.
  • Note: This variable only affects calls made using WHM ports (2086 and 2087). If the call is made via cPanel, it will run as the user who is logged in.
• cpanel_xmlapi_module (string) — Name of the module to access.
  Important: API1 and API2 variables are case-sensitive. For example, specifying Email is different from specifying email.
• cpanel_xmlapi_func (string) — Name of the function to access.

The following variables are optional, depending on the call:

• cpanel_xmlapi_apiversion (integer) — Version of the API to access.
  • 1 — API1.
  • 2 — API2.
  • No input — Defaults to API2.
• arg (string) — List of arguments. These variables are numbered such that the first is arg-0, the second is arg-1, and so on.
  • Example: arg-0=username&arg-1=somepass
  • See below for more examples.

JSON Input

The cpanel JSON function call in Fast Mode takes the following variables as input.

The following variables are required:

• cpanel_jsonapi_user (string) — The user as whom you wish to call the function.
  • Note: This variable only affects calls made using WHM ports (2086 and 2087). If the call is made via cPanel, it will run as the user who is logged in.
• cpanel_jsonapi_module (string) — Name of the module to access.
  • Important: API1 and API2 variables are case-sensitive. For example, specifying Email is different from specifying email.
• cpanel_jsonapi_func (string) — Name of the function to access.

The following variables are optional, depending on the call:

• cpanel_jsonapi_apiversion (integer) — Version of the API to access.
  • 1 — API1.
  • 2 — API2.
  • No input — Defaults to API2.
• API1: arg (string) — List of arguments. These variables are numbered such that the first is arg-0, the second is arg-1, and so on.
  • Example: arg-0=username&arg-1=somepass
  • See below for more examples.
• API2: arg (string) — List of arguments. These variables are given by name.
  • Example: email=bob&domain=fred.com
  • See below for more examples.

Output

• cpanelresult — Container for the result of the cPanel operation.
  • apiversion (string) — Version of API accessed (1 or 2).
  • module (string) — Name of the module accessed.
  • func (string) — Name of the function accessed.
  • type (string) — Type of function.
  • source (string) — Source of the call (internal or external).
  • data — Data provided by the function. (See the function's documentation for information about its data format; documentation is available here.)
    • result (string) — Result of the function.

Examples

The Fast Mode call is formatted like the following examples:

API1 call via XML API

https://example.com:2083/xml-api/cpanel?user=username&cpanel_xmlapi_module=Email&cpanel_xmlapi_func=addpop&cpanel_xmlapi_apiversion=1&arg-0=username&arg-1=somepass&arg-2=10&arg-3=domain.tld

Note: Submit the entire request as a single string. For display purposes, the example above may be wrapped.

This call will result in the following output:

<cpanelresult>
     <apiversion>2</apiversion>
     <func>addpop</func>
     <module>Email</module>
</cpanelresult>

API2 call via XML API

https://example.com:2083/xml-api/cpanel?user=username&cpanel_xmlapi_module=Email&cpanel_xmlapi_func=listpopswithdisk&cpanel_xmlapi_version=2&domain=domain.tld

Note: Submit the entire request as a single string. For display purposes, the example above may be wrapped.

This call will result in the following output:

<cpanelresult>
     <apiversion>2</apiversion>
      <data>
            <_diskquota>250</_diskquota>
             <_diskused>12.81</_diskused>
             <diskquota>250</diskquota>
             <diskused>12.81</diskused>
             <diskusedpercent>5</diskusedpercent>
             <diskusedpercent20>0</diskusedpercent20>
             <domain>domain.tld</domain>
             <email>jane@domain.tld</email>
             <humandiskquota>250 MB</humandiskquota>
             <humandiskused>12.81 MB</humandiskused>
             <login>jane@domain.tld</login>
             <txtdiskquota>250</txtdiskquota>
             <user>jane</user>
       </data>
       <func>listpopswithdisk</func>
       <module>Email</module>
</cpanelresult>

API1 call via JSON API

https://example.com:2083/json-api/cpanel?user=username&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=addpop&cpanel_jsonapi_apiversion=1&arg-0=username&arg-1=somepass&arg-2=10&arg-3=domain.tld

This call will result in the following output:

{
   "apiversion":"1",
   "type":"event",
   "module":"Email",
   "func":addpop",
   "source":"module",
   "data":{
      "result":""
   }
}

Note: Submit the entire request as a single string. For display purposes, the examples above may be wrapped.

API2 call via JSON API

https://example.com:2083/json-api/cpanel?user=username&cpanel_jsonapi_module=Email&cpanel_jsonapi_func=listpopswithdisk&cpanel_jsonapi_version=2&domain=domain.tld

Note: Submit the entire request as a single string. For display purposes, the example above may be wrapped.

This call will result in the following output:

{
   "cpanelresult":{
      "data":[

      ],
      "module":"Email",
      "apiversion":2,
      "func":"listpopswithdisk"
   }
}

Filtering and sorting API 2 output via XML API

When using API 2 functions in XML API, you can also access some meta-variables that allow you to:

• Filter output
• Sort output

XML Mode

Traditionally, XML API calls that accessed the API1 and API2 functions were written in what we call "XML Mode." This type of call is processed somewhat more slowly than the newer calls made using Fast Mode.

Variables

Input

The cpanel function call in XML Mode takes the following variables as input.

The following variables are required:

• user (string) — The username of the owner of the cPanel account to be affected.
• xmlin (XML) — The XML container for the function.
  • Format: <cpanelaction><module></module><func></func><args></args></cpanelaction>
• module (string) — Name of the module to access.
  Important: API1 and API2 variables are case-sensitive. For example, specifying Email is different from specifying email.
• func (string) — Name of the function to access.

The following variables are optional, depending on the call:

• apiversion (integer) — Version of the API to access.
  • 1 — API1.
  • 2 — API2.
  • No input — Defaults to API2.
• args (string) — A container for arguments to pass to the function. For example, a username or password would be surrounded by <args></args>. See below for examples.

Output

• cpanelresult — Root-level XML tag for the output of the cpanel function.
  • apiversion (string) — Version of API accessed (1 or 2).
  • module (string) — Name of the module accessed.
  • func (string) — Name of the function accessed.
  • type (string) — Type of function.
  • source (string) — Source of the call (internal or external).
  • data (XML) — Data provided by the function. (See the function's documentation for information about its data format; documentation is available here.)
    • result (string) — Result of the function.

Examples

The XML Mode call is formatted like the following examples:

API1 call via XML API

https://example.com:2083/xml-api/cpanel?user=username&xmlin=<cpanelaction><module>Email</module><func>addpop</func><apiversion>1</apiversion><args>username</args><args>somepass</args><args>10</args><args>domain.tld</args></cpanelaction>

Note: Submit the entire request as a single string. For display purposes, the example above may be wrapped.

This call will result in the following output:

<cpanelresult>
     <module>Email</module>
     <func>addpop</func>
     <type>event</type>
     <source>internal</source>
     <apiversion>1</apiversion>
     <data>
          <result>username+domain.tld</result>
     </data>
</cpanelresult>

API2 call via XML API

https://example.com:2083/xml-api/cpanel?user=username&xmlin=<cpanelaction><module>Email</module><func>listpopswithdisk</func><args><domain>example.com</domain><nearquotaonly>1</nearquotaonly></args></cpanelaction>

Note: Submit the entire request as a single string. For display purposes, the example above may be wrapped.

This call will result in the following output:

<cpanelresult>
      <apiversion>2</apiversion>
      <data>
            <_diskquota>250</_diskquota>
            <_diskused>12.81</_diskused>
            <diskquota>250</diskquota>
            <diskused>12.81</diskused>
            <diskusedpercent>5</diskusedpercent>
            <diskusedpercent20>0</diskusedpercent20>
            <domain>domain.tld</domain>
            <email>jane@domain.tld</email>
            <humandiskquota>250 MB</humandiskquota>
            <humandiskused>12.81 MB</humandiskused>
            <login>jane@domain.tld</login>
            <txtdiskquota>250</txtdiskquota>
            <user>jane</user>
      </data>
      <func>listpopswithdisk</func>
      <module>Email</module>
</cpanelresult>

Errors returned by the XML and JSON APIs

As noted above, input variables for API1 and API2 are case-sensitive. If you use the wrong case when specifying one of these variables, you may see an error message similar to the following:

• XML API: XML Parsing Error: junk after document element

• JSON API:

{
   "cpanelresult":{
      "apiversion":2,
      "error":"Could not find function 'listfiles' in module 'fileman'",
      "func":"listfiles",
      "module":"fileman"
   }
}

If you see this error, check the syntax of your input variables, making sure to use the correct case for each.