How to Use WHM API Shell: Complete Setup Guide Print

The WHM API Shell lets you test and call WHM API functions directly within your control panel interface. Before you can use this feature, you must enable the "cPanel & WHM API shell (for developers)" setting in WHM's Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings). Only the root user and root-enabled resellers can access this tool.

Important: The API Shell works with live data on your server. API function calls can modify or delete server data, potentially causing system failures. Always read each function's documentation thoroughly before executing any commands through the API Shell, scripts, or other methods.

Enabling the API Shell Feature

To activate the API Shell in WHM:

1. Log into WHM as root or a root-enabled reseller
2. Navigate to WHM >> Home >> Server Configuration >> Tweak Settings
3. Locate the "cPanel & WHM API shell (for developers)" option
4. Enable this setting and save your changes

Once enabled, you can access the API Shell from your WHM interface.

How to Call a WHM API Function

Follow these steps to execute a WHM API function through the API Shell:

1. Select the API version (currently only WHM API version 1 is available through this interface)
2. Choose the function you want to test from the v1 menu
3. Enter the required input parameters and their values
4. Click "Add" if you need to include additional parameters
5. Click the execute button to run the function

The interface will display the API response, showing you the results of your function call in real time.

Filtering, Sorting, and Paginating Results

To customize how results appear, click "Show Sort/Filter/Paginate Options" and configure the following:

Pagination Settings

• Index of first result: Enter a number in the "Index (0-based) of first result to show" box to set which record appears first
• Maximum results: Specify the maximum number of results to display in the "Maximum # of results to show" box

Filtering Results

1. Click "Add" in the Filters section
2. Enter the field name, select a condition from the menu, and enter your search term
3. Add multiple filters by clicking "Add" again

Sorting Results

1. Click "Add" in the Sorts section
2. Enter the field name and select your sort condition
3. Check the "Reverse" checkbox to reverse the sort order
4. Add multiple sort criteria by clicking "Add" again

Limiting Display Columns

1. Click "Add" in the Columns section
2. Specify which columns you want to display in the results
3. Add more columns as needed

Understanding API Function Documentation

Before using any function in the API Shell, review its documentation by clicking "WHM API v1 Documentation" within the interface. The documentation provides:

• Required and optional parameters for each function
• Expected input formats and data types
• Possible return values and error messages
• Usage examples and best practices
• Warnings about functions that modify server data

Best Practices for Using API Shell

When working with the WHM API Shell at OBHost, follow these guidelines:

• Test in development first: If possible, test API functions in a development environment before running them on your production server
• Read documentation: Always review function documentation to understand what changes will occur
• Start with read-only functions: Begin by testing functions that only retrieve information rather than those that modify data
• Use filtering carefully: Apply filters to limit results and reduce server load when working with large datasets
• Keep records: Document the functions you test and their parameters for future reference

Frequently Asked Questions

Who can access the WHM API Shell feature?

Only the root user and resellers with root privileges can use the API Shell. Regular cPanel users and standard resellers cannot access this feature due to its powerful capabilities and potential to modify critical server settings.

Why can't I see the API Shell option in my WHM interface?

If the API Shell isn't visible, you need to enable it first in WHM's Tweak Settings. Navigate to WHM >> Home >> Server Configuration >> Tweak Settings, find the "cPanel & WHM API shell (for developers)" option, enable it, and save your changes. If you still don't see it after enabling, verify that you're logged in as root or a root-enabled reseller.

What happens if I execute a function that modifies server data?

Functions that modify server data will make real changes to your live server immediately. These changes can include creating or deleting accounts, modifying configurations, changing permissions, or altering system settings. There is no "undo" button, so always read the function documentation carefully and understand the consequences before executing any command.

Can I use the API Shell to automate tasks?

While the API Shell is useful for testing and learning how API functions work, it's designed for interactive use rather than automation. For automation, you should use the WHM API directly through scripts (via command line, PHP, Python, or other programming languages) that call the same functions you've tested in the API Shell.

If you need assistance using the WHM API Shell or have questions about specific API functions, our support team is available 24/7. Contact us at https://www.obhost.net/contact or email support@obhost.org for help.