Skip to main content
API docs by Redocly

MCSS API v13 (API_2.3.0)

Documentation for the official MC Server Soft API.

This for MCSS v13.7.0 and higher.

Other versions:

Introduction

Since version 12, MCSS includes an API that allows you to interact with your servers remotely. This documentation is aimed at developers wanting to create apps that utilize the API.

As of right now you can:

  • Run power actions - Start, Stop, Restart or Kill your servers
  • Send commands - run minecraft commands in the console
  • Return server information like the icon, status and description
  • Scheduler CRUD operations (create, read, update & delete tasks)
  • Backup CRUD operations (create, read, update & delete backups)
  • Panel users CRUD operations (create, read, update & delete users)

By default, the API is disabled.

It can be enabled from the settings file > options. Tick the box labeled Enable Web API. After exiting the settings, the API will become available.

Authentication

All API calls require an API key.
This is a header called: apiKey

GET /api/v2 HTTP/1.1
Host: YOUR_IP_ADDRESS:YOUR_PANEL_PORT
apiKey: YOUR_API_KEY

If your key is compromised or lost, it's crucial to act swiftly. In case of exposure, regenerate the key immediately. If lost, delete the old one and generate a new key. Always keep your keys confidential and secure.

API keys can be created in the 'Web Panel' section of mcss:

Screenshot of the "Create new API Key" window, ready to create an API key Screenshot of the "Create new API Key" window, where an API key has been created

Permissions

Permissions can be applied to different users and API keys. This limits the amount of functionality that becomes available for that user/API key.

  • viewStats
  • viewConsole
  • useConsole
  • useServerActions
  • editServer
  • viewBackups
  • createBackup
  • editBackup
  • deleteBackups
  • triggerBackup
  • viewSchedulerTasks
  • createSchedulerTasks
  • editSchedulerTask
  • deleteSchedulerTasks
  • triggerSchedulerTask

These permissions are overwritten when the user or API key has the Admin Permission.

Important note: the Admin permission does not grant you instant access to all servers.

Contributing

Please take into account that these docs are auto generated. Don't spend too much time creating a PR, as most of the changes will probably get overwritten. Create a suggestion based PR instead, so that we can change the source directly and prevent you wasting a lot of time.

General

General API calls that interact with mcss directly.

Get API version

Get version info about mcss.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "isDevBuild": false,
  • "mcssVersion": "13.0.0",
  • "mcssApiVersion": "1.0.0",
  • "uniqueIdentifier": "3664ac4e-23a5-4877-ab75-8412884acdb7",
  • "youAreAwesome": true
}

Servers

API calls that involve multiple servers.

Get list of servers

Return info of all servers.

filter (optional) : enum
0 = None
1 = Minimal
2 = Status

Authorizations:
apiKey
query Parameters
filter
string
Example: filter=None

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get server count

Get the total amount of servers.

filter (optional) : enum
0 = None
1 = Online
2 = Offline
3 = ByServerType

serverTypeId (required when using ByServerType) : guid
Guid of the server type.

ServerTypeIds

Vanilla
349bf6c7-2d19-4e42-bcee-592fa862bcee

CraftBukkit
afa8b9d6-592d-4016-9dd7-eed4185ca8b8

Spigot
de188054-f3ac-472d-81d6-c57f0412bfa6

Paper
f738fb40-223e-4010-bd07-af4caabdf3dd

BungeeCord
1a1bb7be-219f-4dc8-9a6a-4a10dc725391

Waterfall
f49ad4bf-7900-45a4-940b-c97468fbba1f

Forge
8e3aecd7-b81b-4827-a3e2-93a701cdd3b4

Fabric
c45acfcf-b4a1-4733-aab0-f78e1091ae16

Bedrock
87c2620f-48a0-47e6-97c1-ff5fbbc128f3

Purpur
984ed3d3-636d-4535-82b2-7c1048782c64

Authorizations:
apiKey
query Parameters
filter
integer
Example: filter=3
serverTypeId
string
Example: serverTypeId=f738fb40-223e-4010-bd07-af4caabdf3dd

Responses

Response samples

Content type
application/json
{
  • "count": 5
}

Mass execute server action

Change the status of multiple servers.

action : enum
0 = InvalidOrEmpty
1 = Stop
2 = Start
3 = Kill
4 = Restart

serverIds (required) : string[]
List of serverIds where the command should execute.

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "serverIds": [
    ],
  • "action": 1
}

Response samples

Content type
text/plain
null

Mass execute server command

Run a server command on a multiple server.

command (required) : string
Server console command that should be executed.

serverIds (required) : string[]
List of serverIds where the command should execute.

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "serverIds": [
    ],
  • "command": "say hi"
}

Response samples

Content type
text/plain
null

Mass execute server commands

Run multiple server commands on a multiple server.

commands (required) : string[]
List of server console commands that should be executed.

serverIds (required) : string[]
List of serverIds where the command should execute.

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "serverIds": [
    ],
  • "commands": [
    ]
}

Response samples

Content type
text/plain
null

Server

API calls that involve a single server.

Get server details

Return info of a specific server.

filter (optional) : enum
0 = None
1 = Minimal
2 = Status

Authorizations:
apiKey
query Parameters
filter
string
Example: filter=Minimal

Responses

Response samples

Content type
application/json
{
  • "serverId": "e0ae4902-10ed-481f-aed0-fa1170ec779a",
  • "status": 0,
  • "name": "Server Pool",
  • "description": "Pvp & Minigames",
  • "pathToFolder": "P:\\path\\to\\mcss\\servers\\Purpur\\",
  • "folderName": "Purpur",
  • "type": "Purpur",
  • "creationDate": "2021-12-12T12:09:02.820296+01:00",
  • "isSetToAutoStart": false,
  • "forceSaveOnStop": false,
  • "keepOnline": 0,
  • "javaAllocatedMemory": 1025,
  • "javaStartupLine": "java -Xms1G -Xmx1G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:InitiatingHeapOccupancyPercent=15 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper.jar nogui"
}

Edit Server

Update a specific server.

server (required)
- name (optional) : string
- description (optional) : string
- isSetToAutoStart (optional) : boolean
- forceSaveOnStop (optional) : boolean
- javaAllocatedMemory (optional) : int
- keepOnline (optional) : object

KeepOnline Object

- 0 none (default)
- 1 elevated
- 2 aggressive

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "KeepOnline": "Elevated"
}

Response samples

Content type
application/json
{ }

Get server stats

Return stats of a specific server.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "latest": {
    }
}

Get server icon

Return the server-icon.png of a specific server.

Authorizations:
apiKey

Responses

Response samples

Content type
image/png
{}

Execute server action

Change the status of a specific server.

action : enum
0 = InvalidOrEmpty
1 = Stop
2 = Start
3 = Kill
4 = Restart

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "action": 1
}

Response samples

Content type
text/plain
null

Execute server command

Run a server command on a specific server.

command (required) : string
Server console command that should be executed.

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "command": "say My name’s not Kirk..It’s Skywalker. Luke Skywalker."
}

Response samples

Content type
text/plain
null

Execute server commands

Run multiple server commands on a specific server.

commands (required) : string[]
List of server console commands that should be executed.

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "commands": [
    ]
}

Response samples

Content type
text/plain
null

Console

API calls that involve the console from a single server.

Get server console

Return the console of a specific server.

amountOfLines (required) : integer
Amount of lines you want to fetch, -1 to fetch everything.

takeFromBeginning (optional) : boolean
Specify if you want to start fetching from the oldest lines first.

reversed (optional) : boolean
Option to flip the line order.

Authorizations:
apiKey
query Parameters
AmountOfLines
integer
Example: AmountOfLines=5
Reversed
boolean
Example: Reversed=true
takeFromBeginning
boolean
Example: takeFromBeginning=true

Responses

Response samples

Content type
application/json
[
  • "[21:24:12] [Server thread/INFO]: [CraftBook] CraftBook 3.10.6 (1.18.1-1.18.2) is the latest version available, and the updatability of it is: FAIL_NOVERSION. You currently have version CraftBook 3.10.6 (1.18.1-1.18.2) installed.",
  • "[21:24:12] [Thread-17/WARN]: [CraftBook] Please notify the author of this error.",
  • "[21:24:12] [Thread-17/WARN]: [CraftBook] File versions should follow the format 'PluginName vVERSION'",
  • "[21:24:12] [Thread-17/WARN]: [CraftBook] The author of this plugin has misconfigured their Auto Update system",
  • "[21:24:12] [Server thread/INFO]: [CraftBook] 1875 chunk(s) for 3 world(s) processed (109ms elapsed)"
]

Check if console is outdated

Check if your version of the console is outdated. This by sending the last 2 last lines for comparison.

secondLastLine (required)
Second last line you want to check.

lastLine (required)
Last line you want to check.

Authorizations:
apiKey
query Parameters
secondLastLine
string
Example: secondLastLine=%5B19%3A25%3A31%5D%20%5BServer%20thread%2FINFO%5D%3A%20Closing%20Thread%20Pool
lastLine
string
Example: lastLine=%5B19%3A25%3A31%5D%20%5BServer%20thread%2FINFO%5D%3A%20Closing%20Server

Responses

Response samples

Content type
application/json
{
  • "isOutdated": false
}

Scheduler

API calls that involve the scheduler from a single server.

Get scheduler details

Return basic info about the scheduler of a specific server.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "tasks": 8,
  • "interval": 4,
  • "fixedTime": 3,
  • "timeless": 1
}

Get list of tasks

Return all tasks from a specific server.

filter (optional) : enum
0 = None
1 = FixedTime
2 = Interval
3 = Timeless

Authorizations:
apiKey
query Parameters
filter
string
Example: filter=None

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create task

Create a new task.

task (required)
- name (required) : string
- enabled (optional) : boolean
- playerRequirement (optional) : object
- timing (required) : object
- job (required): object

PlayerRequirement Object

- 0 none (default)
- 1 empty
- 2 atLeastOne

Timing Object

fixedTime
- repeat: boolean
- timeSpan: TimeSpan

interval
- repeat: boolean
- interval: integer

timeless
// no parameters

Job Object

ServerAction
- action : ServerAction
// 0 or Stop
// 1 or Start
// 2 or Kill
// 3 or Restart

RunCommands
- commands: string[]

StartBackup
- backupIdentifier: guid

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "Made with the api s",
  • "enabled": true,
  • "playerRequirement": 0,
  • "timing": {
    },
  • "job": {
    }
}

Response samples

Content type
text/plain
null

Get task

Return a specific task from a specific server.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "taskId": "4a582b48-5f37-4586-88f9-a37af96db08a",
  • "name": "Made with the api2",
  • "enabled": false,
  • "playerRequirement": 0,
  • "timing": {
    },
  • "job": {
    }
}

Edit task

Update a specific server task.

You can not change the timing or job object, only its values!

task (required)
- name (optional) : string
- enabled (optional) : boolean
- playerRequirement (optional) : object
- timing (optional) : object
- job (optional): object

PlayerRequirement Object

- 0 none (default)
- 1 empty
- 2 atLeastOne

Timing Object

fixedTime
- repeat: boolean
- timeSpan: TimeSpan

interval
- repeat: boolean
- interval: integer

timeless
// no parameters

Job Object

ServerAction
- action : ServerAction
// 0 or Stop
// 1 or Start
// 2 or Kill
// 3 or Restart

RunCommands
- commands: string[]

StartBackup
- backupIdentifier: guid

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "Start",
  • "enabled": false,
  • "playerRequirement": 1,
  • "timing": {
    },
  • "job": {
    }
}

Response samples

Content type
text/plain
null

Delete task

Delete a specific server task.

Authorizations:
apiKey

Responses

Response samples

Content type
text/plain
null

Run task

Run a specific server task.

Authorizations:
apiKey

Responses

Response samples

Content type
text/plain
null

Backups

API calls that involve backup from a single server.

Get list of backups

Return all backups from a specific server

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create backup

Create a new backup.

backup (required)
- name (required) : string
- destination (required) : string
- suspend(optional) : boolean
- deleteOldBackups (optional) : boolean
- compression (optional) : object
- runBackupAfterCreation (optional): boolean
- fileBlacklist (optional) : string[]
- folderBlacklist (optional) : string[]

Compression Object

- high (default)
- low
- none

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "Test Backup",
  • "destination": "P:\\projects\\MC Server Soft\\dev\\_debug\\backups\\TestApiBackup",
  • "suspend": true,
  • "deleteOldBackups": true,
  • "compression": 1,
  • "runBackupAfterCreation": true,
  • "fileBlacklist": [ ],
  • "folderBlacklist": [ ]
}

Response samples

Content type
text/plain
null

Get list of backups stats

Return all backup stats from a specific server

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "scheduled": 1,
  • "completed": 5,
  • "canceled": 3,
  • "failed": 7
}

Get backup details

Return a specific backup from a specific server.

Compression Object

- 0 high (default)
- 1 low
- 2 none

LastStatus Object

- 0 neverRun (default)
- 1 inProgress,
- 2 completed,
- 3 failed,
- 4 canceled

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "backupId": "fd96b615-6158-4313-85e0-d488f2616ed2",
  • "name": "1/220",
  • "destination": "H:\\backups",
  • "suspend": false,
  • "deleteOldBackups": false,
  • "compression": 1,
  • "lastStatus": 0,
  • "completedAt": "0001-01-01T00:00:00",
  • "fileBlacklist": [ ],
  • "folderBlacklist": [ ]
}

Edit backup

Update a specific server backup.

backup (required)
- name (optional) : string
- destination (optional) : string
- suspend (optional) : boolean
- deleteOldBackups (optional) : boolean
- compression (optional) : object
- runBackupAfterCreation (optional): boolean
- fileBlacklist (optional) : string[]
- folderBlacklist (optional) : string[]

Compression Object

- high (default)
- low
- none

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "name": "Test Edited backup",
  • "compression": 1,
  • "destination": "Hi",
  • "suspend": true,
  • "folderBlacklist": [
    ]
}

Response samples

Content type
text/plain
null

Delete backup

Delete a specific server backup.

Authorizations:
apiKey

Responses

Response samples

Content type
text/plain
null

Run backup

Run a specific server backup.

Authorizations:
apiKey

Responses

Response samples

Content type
text/plain
null

Get backup history

Return the last 15 backup history from a specific server

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Clear backup history

Clear the backup history for a specific server

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{ }

Users

API calls that involve the web panel users.
(API Key must have admin rights)

Get list of users

Return all users from a specific server.
(API Key must have admin rights)

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create User

Create a new user.
(API Key must have admin rights)

user (required)
- username (required) : string
- password (required) : string
- passwordRepeat (required) : string
- enabled (optional) : boolean
- isAdmin (optional) : boolean
- hasAccessToAllServers (optional): boolean
- customServerPermissions (optional) : object[]

CustomServerPermissions Object

serverId (required) : string {
viewStats (required) : boolean,
viewConsole (required) : boolean,
useConsole (required) : boolean,
useServerActions (required) : boolean, editServer(required) : boolean, viewBackups(required) : boolean, createBackup(required) : boolean, editBackup(required) : boolean, deleteBackups(required) : boolean, triggerBackup(required) : boolean, viewSchedulerTasks:(required) : boolean, createSchedulerTasks(required) : boolean, editSchedulerTask(required) : boolean, deleteSchedulerTasks(required) : boolean, triggerSchedulerTask(required) : boolean }

example

"3054aac3-dbf5-4e10-94d2-f4b83577d9b4": {"viewStats": true,"viewConsole": true,"useConsole": true,"useServerActions": true_}_

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "username": "testMadeWithApi",
  • "password": "plaintext",
  • "passwordRepeat": "plaintext",
  • "enabled": true,
  • "isAdmin": false,
  • "hasAccessToAllServers": true,
  • "customServerPermissions": null
}

Response samples

Content type
application/json
{
  • "userId": "b04431ae-692e-496e-8228-d1e912843c7e",
  • "username": "testMadeWithApi",
  • "createdAt": "2023-01-31T18:54:01.4134208Z"
}

Get user details

Return a specific user.
(API Key must have admin rights)

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "userId": "5b488091-625e-4403-8cec-94db3b3cc141",
  • "username": "test",
  • "enabled": true,
  • "isAdmin": false,
  • "hasAccessToAllServers": true,
  • "customServerPermissions": {
    },
  • "createdAt": "2022-08-01T13:07:13.0167083Z",
  • "lastModifiedAt": "2023-01-26T13:01:33.6984964Z"
}

Edit user

Update a specific user.
(API Key must have admin rights) user (required) - password (optional) : string - passwordRepeat (optional) : string - enabled (optional) : boolean - isAdmin (optional) : boolean - hasAccessToAllServers (optional): boolean - customServerPermissions (optional) : object[]

CustomServerPermissions Object

serverId (required) : string { viewStats (required) : boolean, viewConsole (required) : boolean, useConsole (required) : boolean, useServerActions (required) : boolean, editServer(required) : boolean, viewBackups(required) : boolean, createBackup(required) : boolean, editBackup(required) : boolean, deleteBackups(required) : boolean, triggerBackup(required) : boolean, viewSchedulerTasks:(required) : boolean, createSchedulerTasks(required) : boolean, editSchedulerTask(required) : boolean, deleteSchedulerTasks(required) : boolean, triggerSchedulerTask(required) : boolean }

example

"3054aac3-dbf5-4e10-94d2-f4b83577d9b4": {"viewStats": true,"viewConsole": true,"useConsole": true,"useServerActions": true_}_

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "password": "aOfnfydBSBR8%ZgIfy%he$pvm",
  • "passwordRepeat": "aOfnfydBSBR8%ZgIfy%he$pvm",
  • "hasAccessToAllServers": true,
  • "customServerPermissions": null
}

Response samples

Content type
application/json
{ }

Delete user

Delete a specific server user, any active sessions are also removed.
(API Key must have admin rights)

Authorizations:
apiKey

Responses

Response samples

Content type
text/plain
null

Wipe all sessions

Wipes any panel sessions, meaning all users need to relogin.
(API Key must have admin rights)

Authorizations:
apiKey

Responses

Response samples

Content type
text/plain
null

Mcss

Get settings

Get mcss settings.

URL parameters:
- All
- Backups

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "deleteOldBackupsThreshold": 7,
  • "previousBackupLocation": "P:\\path\\to\\backups\\name"
}

Update settings

Update mcss settings.

Authorizations:
apiKey
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "deleteOldBackupsThreshold": 11
}

Response samples

Content type
application/json
{ }