{"id":59897,"date":"2021-02-18T09:16:03","date_gmt":"2021-02-18T15:16:03","guid":{"rendered":"https:\/\/blog.cpanel.com\/?p=59897"},"modified":"2021-02-18T09:16:03","modified_gmt":"2021-02-18T15:16:03","slug":"getting-started-with-the-cpanel-api","status":"publish","type":"post","link":"https:\/\/devel.www.cpanel.net\/blog\/products\/getting-started-with-the-cpanel-api\/","title":{"rendered":"Getting Started With The cPanel\u00ae<\/sup> API"},"content":{"rendered":"\n

cPanel & WHM\u2019s web interfaces offer a comprehensive server and web hosting management solution, but hosts and developers often want to automate tasks or integrate cPanel\u2019s tools with other software. To make that easier, we provide extensive APIs that can be accessed both locally and remotely. <\/p>\n\n\n\n

In this article, we\u2019ll explore the cPanel & WHM APIs and show you how to get started with cPanel\u2019s command-line API utilities and the HTTP API. We have recently updated our API documentation as well at https:\/\/api.docs.cpanel.net\/<\/a><\/p>\n\n\n\n

What Is The cPanel API?<\/strong><\/h2>\n\n\n\n

The cPanel & WHM APIs (Application Programming Interfaces) allow users to access the software\u2019s built-in functionality without going through the web interface. To use the APIs, you send a command, and cPanel responds by carrying out an action, which could be to change a setting, perform a server administration task, or tell you some information. <\/p>\n\n\n\n

There are several benefits to using the APIs.<\/p>\n\n\n\n

  1. They allow users to automate tasks rather than do them manually. For example, as we\u2019ll see in the next section, you can trigger a backup from a script using the API. That script could run on the same server as cPanel or a different server that sends commands over the internet. <\/li>
  2. They allow cPanel to integrate with other tools. A web host might use the API to collect data to display in a dashboard. <\/li>
  3. You can use the APIs to extend cPanel\u2019s functionality. Many cPanel extensions build on the APIs.<\/li><\/ol>\n\n\n\n

    In short, our APIs help users and developers to leverage cPanel\u2019s sophisticated server and hosting administration technologies to solve problems, save time, and build flexible tools for their users.<\/p>\n\n\n\n

    Accessing the cPanel API From Your Server<\/strong><\/h2>\n\n\n\n

    We provide a pair of command-line utilities for scripting and running commands on your server or hosting account, one for the WHM API (whmapi) and the cPanel API (uapi). Functionality is split between them in the same way it\u2019s split between the WHM and cPanel web interfaces, so you would use whmapi for server-related tasks and uapi for hosting-related tasks. <\/p>\n\n\n\n

    To use them, you need to be logged in to your server with SSH<\/a>.<\/p>\n\n\n\n

    First, let\u2019s see how to query the WHM API for information about a server\u2019s user accounts. <\/p>\n\n\n\n

    whmapi list_users<\/code><\/pre>\n\n\n\n
    We\u2019re using the \u201cwhmapi\u201d command to call the \u201clist_users\u201d function. It does precisely what you\u2019d expect, returning a list of users who have accounts on the server, along with some metadata about the command. <\/p>\n\n\n\n
    data:\n\n  users:\n\n    - root\n\n    - user1\n\n    - user2\n\n    - example1\n\nmetadata:\n\n  command: list_users\n\n  reason: OK\n\n  result: 1\n\n  version: 1\n<\/code><\/pre>\n\n\n\n
    Now we know which users have accounts on the server, we want to take a deeper look at one account in particular. <\/p>\n\n\n\n
    whmapi1 accountsummary user=user1<\/code><\/pre>\n\n\n\n
    Here we\u2019re using the \u201caccountsummary\u201d function, and providing the parameter \u201cuser\u201d with the value \u201cuser1\u201d.  A truncated set of results looks like this:<\/p>\n\n\n\n
    data:\n\n  acct:\n    -\n      backup: 1\n\n      disklimit: unlimited\n\n      diskused: 367M\n\n      domain: example.com\n\n      email: user1@example.com\n\n      ip: 198.51.100.13\n<\/code><\/pre>\n\n\n\n
    We see that the account has a domain associated with it, so let\u2019s use the cPanel API to find more information. <\/p>\n\n\n\n
    One common unknown when starting with our API is understanding how masquerading works. Although the cPanel API is designed to be run as the cPanel user, a root user can masquerade as the cPanel user by specifying `–user=<username>` in the UAPI command.<\/p>\n\n\n\n
    uapi --user=user1 DomainInfo list_domains<\/code><\/pre>\n\n\n\n
    The username is given as an option rather than a parameter. Many functions are gathered into modules that provide related functionality. In this case, we\u2019re accessing the \u201cDomainInfo\u201d module and its \u201clist_domains\u201d function. It returns information about all the domains associated with the account.<\/p>\n\n\n\n
    data:\n\n    addon_domains: \n    \t\t\t- example3.com\n\n    main_domain: example.com\n\n    parked_domains: []\n\n    sub_domains:\n\n      - files.example.com\n<\/code><\/pre>\n\n\n\n
    So far we\u2019ve only queried the APIs for information, but they can also be used to instruct cPanel to carry out tasks. For example, let\u2019s say we want to trigger a full backup of this user\u2019s account. To do that, we\u2019d use the \u201cBackup\u201d module with the \u201cfullbackup_to_homedir\u201d function:<\/p>\n\n\n\n
    uapi --user=user1 Backup fullbackup_to_homedir<\/code><\/pre>\n\n\n\n
    Each API includes many modules and dozens of functions capable of automating much of the functionality provided by cPanel & WHM. You will find a full list of modules and more information about using the command-line API utilities in the documentation. <\/p>\n\n\n\n