API Documentation


Content

Setup

Before you can use the API you'll have to enable it under "Settings"->"Panel Configuration".

For each user that should be able to access the API you need to generate an API key. To do this go to the users profile and click on "Generate API Key" in the menu to the left. The API functions that can be called by the users depend on their permissions. If you enable API access for a superuser they can call any function for all the servers.


Usage

In the Multicraft package under "api" you'll find a PHP file "MulticraftAPI.php" that contains a class providing you with an easy to use interface to the Multicraft API.

To use this class just put the file in the same directory as the script that will call the API and in your script you can do the following, for example, to get the server status:
require('MulticraftAPI.php');
$api = new MulticraftAPI('http://example.com/multicraft/api.php', 'demo', '#6nh%tX=ot$sBX');
print_r($api->getServerStatus(1, true));
In this example "http://example.com/multicraft/api.php" is the URL to your Multicraft control panel, with "api.php" appended. "demo" is the user you'd like to access the API as and "#6nh%tX=ot$sBX" is the API key for that user.

The function call "$api->getServerStatus(1, true);" will return the status of the server with ID 1 - including the names of players currently on the server - as an array:
array(
    'success' => true,
    'errors' => array(),
    'data' => array(
        'status' => 'online',
        'onlinePlayers' => '1',
        'players' => array(
            0 => array(
                'ip' => '192.168.1.149',
                'id' => '12',
                'name' => 'Player'
            )
        )
        'maxPlayers' => '16'
    )
)


Parameters

All parameters are normal PHP variables and should be self explanatory in the function listing below. The only functions that allow arrays to be passed are the "find" and "update" functions.
The general convention for the "find" and "update" functions is:
$api->findUsers('name', '=admin');
to find the user named "admin" or
$api->findUsers(array('name', 'email'), array('test', '@example.com'));
to find all users that have the string "test" in their name and "@example.com" in their email address.


Return Values

All functions return an array in the form of:
array(
    'success' => true,
    'errors' => array(),
    'data' => array(),
)
Where 'success' is either true or false, 'errors' is an array of error strings and 'data' is the data returned by the API call.


Examples

Find user with exact email match:
$response = $api->findUsers('email', '='.$email);
if ($response['success'])
{
    $user = $response['data']['Users'];
    foreach ($user as $id=>$name)
        echo 'Name: '.$name.', ID: '.$id.'<br/>';
}

Find user with partial email match:
$response = $api->findUsers('email', $partialEmail);
if ($response['success'])
{
    $user = $response['data']['Users'];
    foreach ($user as $id=>$name)
        echo 'Name: '.$name.', ID: '.$id.'<br/>';
}

Create a new server:
$api->createServer('New Minecraft Server');

Create a new server on a specific daemon:
$api->createServerOn($daemonId);

Update multiple server settings at once. Change memory, change IP, auto generate port:
$response = $api->updateServer($serverId, array(
        'memory',
        'ip',
        'port',
    ),
    array(
        $newMemory,
        $newIp,
        0,
    )
);

Enable Users to change the JAR file and the slot count:
$response = $api->updateServerConfig($serverId, array(
        'user_jar',
        'user_players',
    ),
    array(
        true,
        true,
    )
);

Move server to another daemon, also moving server files:
$response = $api->moveServer($serverId, $daemonId);


Functions

Function signature Return value
User functions
listUsers()
array (
  'Users' => 
  array (
    1 => 'admin',
  ),
)
findUsers(field, value)
array (
  'Users' => 
  array (
    2 => 'tester',
    3 => 'testUser2',
  ),
)
getUser(id)
array (
  'User' => 
  array (
    'id' => '1',
    'name' => 'admin',
    'email' => 'admin@localhost',
    'global_role' => 'none',
  ),
)
getCurrentUser() (2.0.0)
array (
  'User' => 
  array (
    'id' => '1',
    'name' => 'admin',
    'email' => 'admin@localhost',
    'global_role' => 'none',
  ),
)
updateUser(id, field, value)
array (
)
createUser(name, email, password)
array (
  'id' => 2,
)
deleteUser(id)
array (
)
getUserRole(user_id, server_id)
array (
  'role' => 'owner',
)
setUserRole(user_id, server_id, role)
array (
)
getUserFtpAccess(user_id, server_id)
array (
  'mode' => 'rw',
)
setUserFtpAccess(user_id, server_id, mode)
array (
)
getUserId(name)
array (
  'id' => 3,
)
validateUser(name, password) (2.0.0)
array (
)
generateUserApiKey(user_id) (2.0.0)
array (
    [api_key] => 123abc
)
getUserApiKey(user_id) (2.0.0)
array (
    [api_key] => 123abc
)
removeUserApiKey(user_id) (2.0.0)
array (
)
Player functions
listPlayers(server_id)
array (
  'Players' => 
  array (
    2 => 'Test_Player2',
  ),
)
findPlayers(server_id, field, value)
array (
  'Players' => 
  array (
    1 => 'Test_Player',
  ),
)
getPlayer(id)
updatePlayer(id, field, value)
array (
)
createPlayer(server_id, name)
array (
  'id' => 2,
)
deletePlayer(id)
array (
)
assignPlayerToUser(player_id, user_id)
array (
)
Command functions
listCommands(server_id)
array (
  'Commands' => 
  array (
    18 => 'Test_Command',
  ),
)
findCommands(server_id, field, value)
array (
  'Commands' => 
  array (
    18 => 'Test_Command',
  ),
)
getCommand(id)
updateCommand(id, field, value)
array (
)
createCommand(server_id, name, role, chat, response, run)
array (
  'id' => 18,
)
deleteCommand(id)
array (
)
Server functions
listServers()
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
findServers(field, value)
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
listServersByConnection(connection_id)
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
listServersByOwner(user_id)
array (
  'Servers' => 
  array (
    3 => 'Minecraft Server',
  ),
)
getServer(id)
array (
  'Server' => 
  array (
    'id' => '1',
    'name' => 'Test Server',
    'ip' => '',
    'port' => '25565',
    'dir' => 'server1',
    'world' => '',
    'players' => '8',
    'memory' => '0',
    'start_memory' => '0',
    'jarfile' => '',
    'autostart' => '0',
    'default_level' => '10',
    'daemon_id' => '1',
    'announce_save' => '1',
    'kick_delay' => '3000',
    'suspended' => '0',
  ),
)
updateServer(id, field, value)
array (
)
createServerOn(daemon_id = 0, no_commands = 0, no_setup_script = 0)
array (
  'id' => 1,
)
createServer(name = '', port = 0, base = '', players = 0, no_setup_script = 0)
array (
  'id' => 1,
)
suspendServer(id, stop = 1)
array (
)
resumeServer(id, start = 1)
array (
)
deleteServer(id, delete_dir = 'no', delete_user = 'no')
array (
)
getServerStatus(id, player_list = 0)
array (
  'status' => 'online',
  'onlinePlayers' => 0,
  'players' => 
  array (
  ),
  'maxPlayers' => '8',
)
getServerOwner(server_id)
array (
  'user_id' => 2,
)
setServerOwner(server_id, user_id)
array (
)
getServerConfig(id)
array (
  'ServerConfig' => 
  array (
    'server_id' => '1',
    'ip_auth_role' => 'guest',
    'give_role' => 'mod',
    'tp_role' => 'mod',
    'summon_role' => 'mod',
    'chat_role' => 'user',
    'user_jar' => '0',
    'user_ftp' => '0',
    'visible' => '1',
    'user_schedule' => '1',
  ),
)
updateServerConfig(id, field, value)
array (
)
startServerBackup(id)
array (
)
getServerBackupStatus(id)
array (
  'status' => 'running',
  'time' => '0',
  'message' => '[World: world] ',
  'file' => '/home/minecraft/multicraft/servers/server1/world.zip',
  'ftp' => '192.168.1.75:21',
)
startServer(id)
array (
)
stopServer(id)
array (
)
restartServer(id)
array (
)
killServer(id) (2.0.0)
array (
)
startAllServers()
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
stopAllServers()
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
restartAllServers()
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
killAllServers() (2.0.0)
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
sendConsoleCommand(server_id, command)
array (
)
sendAllConsoleCommand(command)
array (
  '[1]success' => true,
  '[1]data' => 
  array (
  ),
  '[1]error' => false,
)
runCommand(server_id, command_id, run_for = 0)
array (
)
getServerLog(id)
array (
  0 => 
  array (
    'line' => '/Loading Minecraft instance properties/',
  ),
)
clearServerLog(id)
array (
)
getServerChat(id)
clearServerChat(id)
array (
)
sendServerControl(id, command) (2.0.0)
array (
)
getServerResources(id) (2.0.0)
array (
    [cpu] => 0
    [memory] => 0
)
moveServer(server_id, daemon_id) (2.0.0)
array (
)
Daemon functions
listConnections()
array (
  'Daemons' => 
  array (
    1 => '',
  ),
)
findConnections(field, value)
array (
  'Daemons' => 
  array (
    1 => '',
  ),
)
getConnection(id)
removeConnection(id)
array (
)
getConnectionStatus(id)
getConnectionMemory(id, include_suspended = 0)
array (
  'total' => 2048,
  'used' => 1024,
)
getStatistics(daemon_id = 0, include_suspended = 0) (2.0.0)
array (
    [daemons] => 1
    [daemon_memory] => 2048
    [servers] => 1
    [players] => 8
    [assigned_memory] => 256
)
Settings functions
listSettings()
array (
  'Settings' => 
  array (
    'dbVersion' => '5',
    'updateChecks' => '1',
    'anonStats' => '1',
  ),
)
getSetting(key)
array (
  'Setting' => 
  array (
    'key' => 'updateChecks',
    'value' => '1',
  ),
)
setSetting(key, value)
array (
)
deleteSetting(key)
array (
)
Schedule functions
listSchedules(server_id)
array (
  'Schedules' => 
  array (
    1 => 'test schedule',
    2 => 'Test schedule 2',
  ),
)
findSchedules(server_id, field, value)
array (
  'Schedules' => 
  array (
    1 => 'test schedule',
    2 => 'Test schedule 2',
  ),
)
getSchedule(id)
updateSchedule(id, field, value)
array (
)
createSchedule(server_id, name, ts, interval, cmd, status, for)
array (
  'id' => 1,
)
deleteSchedule(id)
array (
)
Database functions
getDatabaseInfo(server_id) (2.0.0)
array (
    [host] => localhost
    [name] => mctemp_1
    [username] => mctemp_1
    [password] => 123abc
    [link] => 
)
createDatabase(server_id) (2.0.0)
array (
    [host] => localhost
    [name] => mctemp_1
    [username] => mctemp_1
    [password] => 123abc
    [link] => 
)
changeDatabasePassword(server_id) (2.0.0)
array (
    [host] => localhost
    [name] => mctemp_1
    [username] => mctemp_1
    [password] => 456def
    [link] => 
)
deleteDatabase(server_id) (2.0.0)
array (
)