Please keep in mind that our API is provided as a free extra, we do not provide support for getting this set up, and we do not guarantee it will always be online and available.

PebbleHost Panel API

Our panel has an API which allows you to manage your server from an automated program, monitor your server, and more! Our API is based off the Multicraft API however we've made a number of changes, below the implementation is detailed.



Calling the API

Our API is accessible through the url https://panel.pebblehost.com/api.php. It accepts a POST request, all parameters are then encoded into the post body.

Parameters are encoded using a querystring format. This means the values are encoded into key=value, each value is url-encoded replacing special characters with their URL equivalent, and multiple keys are joined with a & character. For example, the following object:

{
    "_MulticraftAPIMethod": "setUserFtpAccess",
    "_MulticraftAPIUser": "example@pebblehost.com",
    "server_id": 123456,
    "user_id": 654321,
    "mode": "rw",
    "_MulticraftAPIKey": "f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f"
}

Would be encoded as:

_MulticraftAPIMethod=setUserFtpAccess&_MulticraftAPIUser=example%40pebblehost.com&server_id=123456&user_id=654321&mode=rw&_MulticraftAPIKey=f6952d6eef555ddd87aca66e56b91530222d6e318414816f3ba7cf5bf694bf0f


Authentication

Our API does not support the sub-user permissions system, only the main owner can make requests using the API.

Each request requires three special parameters as well as the actual request data. These are _MulticraftAPIMethod, _MulticraftAPIUser, and _MulticraftAPIKey.

  • _MulticraftAPIMethod - The exact name of the method you wish to use, as detailed below
  • _MulticraftAPIUser - The email of the account
  • _MulticraftAPIKey - A hashed checksum of the authentication data of the request

Calculating the _MulticraftAPIKey is quite complex as it involves looping through each parameter. First, start with an array/object of your parameters. The first two parameters should be the _MulticraftAPIMethod and _MulticraftAPIUser, then any specific arguments such as server_id. Do not include the _MulticraftAPIKey in this array.

Then, to calculate the _MulticraftAPIKey, append all the parameters onto a single string without using either = or &. For example, with the example object in "Calling the API", you should end up with the following string:

_MulticraftAPIMethodsetUserFtpAccess_MulticraftAPIUserexample%40pebblehost.comserver_id123456user_id654321mode=rw

Next, you will need to make a SHA256 HMAC of this string, encoded using your Multicraft API Key taken from the panel. Here's a code example in Node.JS:

const crypto = require("crypto");

const key = "EX4MPL3";
const hmac = crypto.createHmac("sha256", key);

const paramsString = "_MulticraftAPIMethodsetUserFtpAccess_MulticraftAPIUserexample%40pebblehost.comserver_id123456user_id654321mode=rw";
hmac.update(paramsString);

const digest = hmac.digest("hex");
console.log(digest);
// eb121f81247d3bfdd1f88053e8924a983819fa5af6e51609bc8ff27624d80c27

Finally, you would take that generated hash and add it as a _MulticraftAPIKey parameter to the request as the last parameter. So in total, for the example request used previously, with an API key of EX4MPL3 the final POST body would be:

_MulticraftAPIMethod=setUserFtpAccess&_MulticraftAPIUser=example%40pebblehost.com&server_id=123456&user_id=654321&mode=rw&_MulticraftAPIKey=eb121f81247d3bfdd1f88053e8924a983819fa5af6e51609bc8ff27624d80c27


Working Example

Here's some sample Node.JS code to make a call to our API:

const axios = require("axios");
const querystring = require('querystring');
const crypto = require("crypto");

async function makeRequest(method, content = {}, user, key) {
    let keystr = "";
    let params = content ? content : {};

    // Add API method & user
    params["_MulticraftAPIMethod"] = method;
    params["_MulticraftAPIUser"] = user;

    // Generate string to then HMAC it
    for (var param in params) {
        if (!params.hasOwnProperty(param)) continue;
        keystr += param + params[param].toString();
    }

    // Creates HMAC of parameters, using Multicraft API key as message key
    let hmac = crypto.createHmac('sha256', key);
    hmac.update(keystr);
    let digest = hmac.digest('hex');

    // Add generated digest to parameters
    params["_MulticraftAPIKey"] = digest;

    try {
        // Use library to encode parameters into querystring body
        const encodedParams = querystring.stringify(params);

        // Make request to panel API
        const { data } = await axios.post("https://panel.pebblehost.com/api.php", encodedParams, {
            // Encourage Cloudflare to allow the request
            headers: {
                'User-Agent': 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0',
                'Referer': 'https://panel.pebblehost.com'
            }
        });
        return data;
    } catch (e) {
        throw new Error("API responded with error status " + e.status);
    }
}


API Methods

Most of the API methods are documented on Multicraft's site however for the requests we have added, the parameter information is included below. We have only included API calls which users have permission to access.


[
    //User functions
    'getCurrentUser'            => [],
    'getUserPermissions'        => ['user_id', 'server_id'],
    'setUserPermission'         => ['user_id', 'server_id', 'action_name', 'value'],
    'removeUserPermissions'     => ['user_id', 'server_id'],
    'getAuditLogs'              => ['server_id', 'user_id', 'user_name', 'category', 'type'],
    'getUserFtpAccess'          => ['user_id', 'server_id'],
    'setUserFtpAccess'          => ['user_id', 'server_id', 'mode'],
    'getOwnApiKey'              => ['password', ['name'=>'generate', 'default'=>0], ['name'=>'gauth_code', 'default'=>'']],
    //Player functions
    'listPlayers'               => ['server_id'],
    'findPlayers'               => ['server_id', ['name'=>'field', 'type'=>'array'], ['name'=>'value', 'type'=>'array']],
    'getPlayer'                 => ['id'],
    'updatePlayer'              => ['id', ['name'=>'field', 'type'=>'array'], ['name'=>'value', 'type'=>'array']],
    'createPlayer'              => ['server_id', 'name', ['name'=>'op_command', 'default'=>0]],
    'deletePlayer'              => ['id'],
    'assignPlayerToUser'        => ['player_id', 'user_id'],
    //Command functions
    'listCommands'              => ['server_id'],
    'findCommands'              => ['server_id', ['name'=>'field', 'type'=>'array'], ['name'=>'value', 'type'=>'array']],
    'getCommand'                => ['id'],
    'updateCommand'             => ['id', ['name'=>'field', 'type'=>'array'], ['name'=>'value', 'type'=>'array']],
    'createCommand'             => ['server_id', 'name', 'role', 'chat', 'response', 'run'],
    'deleteCommand'             => ['id'],
    //Server functions
    'listServersByOwner'        => ['user_id'],
    'getServer'                 => ['id'],
    'updateServer'              => ['id', ['name'=>'field', 'type'=>'array'], ['name'=>'value', 'type'=>'array']],
    'getServerStatus'           => ['id', ['name'=>'player_list', 'default'=>0]],
    'startServer'               => ['id'],
    'stopServer'                => ['id'],
    'restartServer'             => ['id'],
    'killServer'                => ['id'],
    'sendConsoleCommand'        => ['server_id', 'command'],
    'runCommand'                => ['server_id', 'command_id', ['name'=>'run_for', 'default'=>0]],
    'getServerLog'              => ['id'],
    'clearServerLog'            => ['id'],
    'getServerChat'             => ['id'],
    'clearServerChat'           => ['id'],
    'getServerResources'        => ['id'],
    //Schedule functions
    'listSchedules'             => ['server_id'],
    'findSchedules'             => ['server_id', ['name'=>'field', 'type'=>'array'], ['name'=>'value', 'type'=>'array']],
    'getSchedule'               => ['id'],
    'updateSchedule'            => ['id', ['name'=>'field', 'type'=>'array'], ['name'=>'value', 'type'=>'array']],
    'createSchedule'            => ['server_id', 'name', 'ts', 'interval', 'cmd', 'status', 'for'],
    'deleteSchedule'            => ['id'],
    //Database functions
    'getDatabaseInfo'           => ['server_id'],
    'createDatabase'            => ['server_id', 'name', 'password'],
    'changeDatabasePassword'    => ['server_id', 'database_id', 'password'],
    'deleteDatabase'            => ['server_id', 'database_id']
];