The cPanel API Shell is an interactive tool that lets you run cPanel API functions directly in your control panel. This feature is designed for developers and advanced users who want to test API calls before implementing them in scripts or applications. However, because the API Shell uses live server data, all function calls make real changes to your account, so proceed with caution.
Before using any API function, carefully read its documentation to understand what it does. The API Shell is a powerful tool that can modify or delete server data, potentially causing issues if used incorrectly.
Enabling API Shell in cPanel
The API Shell feature must be enabled by your hosting provider before you can access it. If you don't see this option in your cPanel, contact your provider to request access.
Your hosting provider needs to complete two steps in WHM (Web Host Manager):
- Enable the setting called cPanel & WHM API shell (for developers) in the System tab of Tweak Settings
- Grant the API Shell feature to your account through the Feature Manager in WHM
Important: You must use a reseller account to access the API Shell interface. Standard hosting accounts cannot access this feature even if it's enabled.
Choosing Your API Version
The API Shell supports two cPanel API versions:
- UAPI: The current recommended API with modern functionality and consistent structure
- cPanel API 2: The legacy API that still works but is no longer actively developed
For new projects, use UAPI whenever possible. It offers better documentation, clearer responses, and improved error handling.
How to Call an API Function
Follow these steps to test an API function in the API Shell:
- Select your preferred API version (UAPI or cPanel API 2) from the dropdown menu
- Choose the specific API function you want to test from the function list
- Enter the required keys and values for your function parameters
- Click Add to include additional parameters if needed
- Click the execute button to run the function
The interface will display the results immediately, showing you the exact response your API call generates.
Filtering and Sorting Results
Many API functions return large datasets. To manage these results effectively, click Show Sort/Filter/Paginate Options to access advanced controls:
- Starting position: Enter a number in the Index of first results to show field to skip ahead in results (zero-based indexing)
- Result limit: Set the Maximum # of results to show to control how many records display
- Filters: Click Add in the Filters section to create custom filters based on specific fields and values
- Sorting: Use the sort options to arrange results by any available field in ascending or descending order
These options help you narrow down results when testing functions that return extensive data.
Safety Tips for Using API Shell
The API Shell executes real commands on your live server. Keep these safety guidelines in mind:
- Always read the complete documentation for a function before executing it
- Test with non-critical data first when trying a new function
- Double-check all parameter values before clicking execute
- Keep a backup of important data before running destructive operations
- Review the example outputs in the cPanel Developer Documentation to understand expected results
Functions that create, modify, or delete data (like domain management or file operations) take immediate effect. There is no undo button in the API Shell.
Understanding API Responses
After executing a function, the API Shell displays the response in JSON format. Successful responses typically include:
- Status indicators showing whether the call succeeded
- Requested data or confirmation of the completed action
- Metadata about the response
Failed responses show error messages explaining what went wrong, which helps you troubleshoot issues with your API calls.
Common Use Cases
Developers and system administrators use the API Shell for several purposes:
- Testing API functions before implementing them in automated scripts
- Troubleshooting API integration issues
- Learning how different API functions work
- Prototyping new features that rely on cPanel APIs
- Verifying parameter requirements and response formats
The interactive nature of the API Shell makes it an excellent learning tool for understanding cPanel's API capabilities.
Best Practices
Follow these recommendations when working with the API Shell:
- Start with read-only functions (like listing accounts or viewing settings) before trying functions that modify data
- Keep the cPanel Developer Documentation open in another tab for quick reference
- Test each parameter combination thoroughly in a development environment
- Document the API calls that work well for future reference
- Use meaningful test data that helps you verify results
Taking a methodical approach to API testing prevents errors and helps you build reliable integrations.
Frequently Asked Questions
Why can't I see the API Shell option in my cPanel?
The API Shell feature must be explicitly enabled by your hosting provider through WHM. If you don't see it in your cPanel interface, contact your provider at their support team and ask them to enable the API Shell feature for your account. Additionally, you need a reseller account to access this feature.
What's the difference between UAPI and cPanel API 2?
UAPI is the current, modern API with better structure and documentation. cPanel API 2 is the older version that still works but receives limited updates. For new projects, always choose UAPI unless you need a specific function that's only available in API 2. UAPI provides more consistent responses and clearer error messages.
Can I undo changes made through the API Shell?
No, the API Shell executes commands on your live server immediately with no undo option. Any changes to accounts, files, domains, or settings happen instantly and permanently. Always review your parameters carefully before executing functions, and consider testing in a development environment first if you're unsure about a function's behavior.
How do I know which parameters a function requires?
Refer to the official cPanel Developer Documentation for complete parameter lists and descriptions for each function. The documentation shows required parameters, optional parameters, expected data types, and example requests with responses. The API Shell interface also displays available parameters once you select a function, but the full documentation provides crucial context about how to use them correctly.
The OBHost support team is available 24/7 to help with any questions about using cPanel features. Visit our contact page or email support@obhost.org for assistance.
