Introduction

Important information

A valid token passed via the Authorization HTTP header is required for every single endpoint except /api/v2/login, /api/v2 and /api/v2/jsonschema/*
A superuser always has access to all the servers and has all the Crafty and server permissions.
When a "server permission" is mentioned, it's automatically assumed that the user has access to the current server.
When a "Crafty permission" is mentioned, it's automatically assumed that the user does not exceed the creation limit.

XH examples

I'll feature examples using the XH HTTP client and some shell for some endpoints. Please set a shell variable with the name of token if you intend to try the examples.

Example request in raw HTTP

POST /api/v2/users HTTP 1.1
Authorization: Bearer <token here>
Content-Type: application/json

{
    "username": "test",
    "password": "test",
    "manager": "1"
    "email": "[email protected]",
    "lang": "fi_FI",
    "superuser": true,
    "theme": "dark",
}

JSON schemas

You can get all the JSON schema names by requesting /api/v2/jsonschema.
You can get an individual JSON schema by requesting /api/v2/jsonschema/<schema name here>.
You can get some default values for schemas by using https://json-schema-faker.js.org. I recommend setting the useExamplesValue option to true.

Here is a list of available JSON schemas found at jsonschema.py:

login
modify_role
create_role
server_patch
new_server
user_patch
new_user
task_patch

API V2 Endpoints

Authentication requests

Log out every single session the token's user has

Response data in practice	Nothing important
Permission(s) required	Logged in

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/auth/invalidate_tokens

POST /api/v2/auth/invalidate_tokens

Example response body:

{
  "status": "ok"
}

Log in and get a token

Response data in practice	The user ID and a new JWT
Permission(s) required	None
JSON schema	`login`

XH example(s):

token="$(xh POST https://localhost:8443/api/v2/auth/login -- username=admin password=crafty | jq .data.token -r)"

POST /api/v2/auth/login

Example request body:

{
    "username": "test",
    "password": "test"
}

Example response body:

{
    "status": "ok",
    "data": {
        "token": "<token here>",
        "user_id": "1"
    }
}

Role requests

Get all the roles

Response data in practice	All the roles or only the IDs if requested
Permission(s) required	Superuser

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/roles

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/roles\?ids\=true

GET /api/v2/roles

GET /api/v2/roles?ids=true

Example response body for the path /api/v2/roles:

{
    "status": "ok",
    "data": [
        {
            "role_id": 1,
            "created": "05/18/2022, 16:25:45",
            "last_update": "2022-05-18T16:25:45.377352",
            "role_name": "test 1234"
        }
    ]
}

Example response body for the path /api/v2/roles?ids=true:

{
    "status": "ok",
    "data": [
        1
    ]
}

Create a role

Response data in practice	The new role's ID
Permission(s) required	Superuser
JSON schema	`create_role`

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/roles -- name='test 1234' servers:='[{"server_id": 1, "permissions": "10101101"}]'

POST /api/v2/roles

Example request body:

{
    "name": "test role 1234",
    "servers": [
        {
            "server_id": 1,
            "permissions": "10101101"
        }
    ]
}

Example response body:

{
    "status": "ok",
    "data": {
        "role_id": 1
    }
}

Get a role

Response data in practice	The role's data
Permission(s) required	Superuser
URL `role_id` placeholder	The role's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/roles/1

GET /api/v2/roles/<role_id>

Example response body:

{
    "status": "ok",
    "data": {
        "role_id": 1,
        "created": "05/18/2022, 22:49:11",
        "last_update": "2022-05-18T16:25:45.377352",
        "role_name": "test 1234"
    }
}

Get a role's servers

Response data in practice	The servers or only the IDs if requested
Permission(s) required	Superuser
URL `role_id` placeholder	The role's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/roles/1/servers

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/roles/1/servers\?ids\=true

GET /api/v2/roles/<role_id>/servers

GET /api/v2/roles/<role_id>/servers?ids=true

Example response body for the path /api/v2/roles/<role_id>/servers:

{
    "status": "ok",
    "data": [
        {
            "server_id": 1,
            "permissions": "10101101"
        }
    ]
}

Example response body for the path /api/v2/roles/<role_id>/servers?ids=true:

{
    "status": "ok",
    "data": [
        1
    ]
}

Get a role's users

Response data in practice	The users
Permission(s) required	Superuser
URL `role_id` placeholder	The role's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/roles/1/users

GET /api/v2/roles/<role_id>/users

Example response body:

{
    "status": "ok",
    "data": [
        1
    ]
}

Delete a role

Response data in practice	Nothing important
Permission(s) required	Superuser
URL `role_id` placeholder	The role's ID

XH example(s):

xh -A bearer -a "$token" DELETE https://localhost:8443/api/v2/roles/2

DELETE /api/v2/roles/<role_id>

Example response body:

{
    "status": "ok"
}

Modify a role

Response data in practice	Nothing important
Permission(s) required	Superuser
JSON schema	`modify_role`
URL `role_id` placeholder	The role's ID

XH example(s):

xh -A bearer -a "$token" PATCH https://localhost:8443/api/v2/roles/1 -- name='renamed test role 1234' servers:='[{"server_id": 1, "permissions": "10101101"}]'

PATCH /api/v2/roles/<role_id>

Example request body:

{
    "name": "renamed test role 1234",
    "servers": [
        {
            "server_id": 1,
            "permissions": "10101101"
        }
    ]
}

Example response body: <syntaxhighlight lang="json> { {{__snippet|post|154|pre}} } </syntaxhighlight>

<h2>Server requests

Get all the servers

Response data in practice	All the servers you have access to
Permission(s) required	Logged in

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers

GET /api/v2/servers

Example response body:

{
    "status": "ok",
    "data": [
        {
            "server_id": 1,
            "created": "2022-05-18T22:36:04.751211",
            "server_uuid": "e7e107ed-b4fd-4f87-b2dd-b66b4930706e",
            "server_name": "test server",
            "path": "/servers/e7e107ed-b4fd-4f87-b2dd-b66b4930706e",
            "backup_path": "/backups/e7e107ed-b4fd-4f87-b2dd-b66b4930706e",
            "executable": "paper-1.18.2.jar",
            "log_path": "/servers/e7e107ed-b4fd-4f87-b2dd-b66b4930706e/logs/latest.log",
            "execution_command": "java -Xms1000M -Xmx2000M -jar /servers/e7e107ed-b4fd-4f87-b2dd-b66b4930706e/paper-1.18.2.jar nogui",
            "auto_start": false,
            "auto_start_delay": 10,
            "crash_detection": false,
            "stop_command": "stop",
            "executable_update_url": "",
            "server_ip": "127.0.0.1",
            "server_port": 25565,
            "logs_delete_after": 0,
            "type": "minecraft-java"
        }
    ]
}

Create a server

Response data in practice	The new server's ID and directory UUID
Permission(s) required	Crafty permission `SERVER_CREATION`
JSON schema	`new_server`

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/servers -- name='api doc server' monitoring_type='minecraft_java' minecraft_java_monitoring_data:='{"host": "127.0.0.1", "port": 25565}' create_type='minecraft_java' minecraft_java_create_data:='{"create_type": "download_jar", "download_jar_create_data": {"category": "servers", "type": "Paper","version": "1.18.2","mem_min": 1,"mem_max": 2,"server_properties_port": 25565,"agree_to_eula": true}}'

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/servers -- name='api doc bedrock server' monitoring_type='minecraft_bedrock' minecraft_bedrock_monitoring_data:='{"host": "127.0.0.1", "port": 19132}' create_type='minecraft_bedrock' minecraft_bedrock_create_data:='{"create_type": "import_server", "import_server_create_data": {"existing_server_path": "/var/opt/server","command": "env LD_LIBRARY_PATH=. ./bedrock_server"}}'

POST /api/v2/servers

Example request bodies:

{
    "name": "api doc server",
    "monitoring_type": "minecraft_java",
    "minecraft_java_monitoring_data": {
        "host": "127.0.0.1",
        "port": 25565
    },
    "create_type": "minecraft_java",
    "minecraft_java_create_data": {
        "create_type": "download_jar",
        "download_jar_create_data": {
            "type": "Paper",
            "version": "1.18.2",
            "mem_min": 1,
            "mem_max": 2,
            "server_properties_port": 25565,
            "agree_to_eula": true
        }
    }
}

{
    "name": "api doc bedrock server",
    "monitoring_type": "minecraft_bedrock",
    "minecraft_bedrock_monitoring_data": {
        "host": "127.0.0.1",
        "port": 19132
    },
    "create_type": "minecraft_bedrock",
    "minecraft_bedrock_create_data": {
        "create_type": "import_server",
        "import_server_create_data": {
            "existing_server_path": "/var/opt/server",
            "command": "env LD_LIBRARY_PATH=. ./bedrock_server"
        }
    }
}

Example response body:

{
    "status": "ok",
    "data": {
        "new_server_id": "1",
        "new_server_uuid": "f53b7b9d-48cc-40f1-89ce-331bda9458ba"
    }
}

Get a server

Response data in practice	The server's data
Permission(s) required	Access to the server
URL `server_id` placeholder	The server's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1

GET /api/v2/servers/<server_id>

Example response body:

{
    "status": "ok",
    "data": {
        "role_id": 1,
        "created": "05/18/2022, 22:49:11",
        "last_update": "2022-05-18T16:25:45.377352",
        "role_name": "test 1234"
    }
}

Delete a server

Response data in practice	Nothing important
Permission(s) required	Server permission `CONFIG`
URL `server_id` placeholder	The server's ID

XH example(s):

xh -A bearer -a "$token" DELETE https://localhost:8443/api/v2/servers/1

DELETE /api/v2/servers/<server_id>

Example response body:

{
    "status": "ok"
}

Modify a server

Response data in practice	Nothing important
Permission(s) required	Server permission `CONFIG`
JSON schema	`server_patch`
URL `server_id` placeholder	The server's ID

XH example(s):

xh -A bearer -a "$token" PATCH https://localhost:8443/api/v2/servers/1 -- server_name='api test server'

PATCH /api/v2/servers/<server_id>

Example request body:

{
    "server_name": "api test server"
}

Example response body:

{
    "status": "ok"
}

Send an action to a server

Response data in practice	Nothing important, or the new server's ID is cloning a server
Permission(s) required	Server permission `COMMANDS`
URL `server_id` placeholder	The server's ID
URL `action` placeholder	One of `clone_server`, `start_server`, `stop_server`, `restart_server`, `kill_server`, `backup_server`, `update_executable`

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/servers/1/action/start_server

POST /api/v2/servers/<server_id>/action/<action>

Example response bodies:

{
    "status": "ok"
}

{
    "status": "ok"
    "data": {
        "new_server_id": "3"
    }
}

Send a STDIn command to a server

Response data in practice	Nothing important
Permission(s) required	Server permission `COMMANDS`
URL `server_id` placeholder	The server's ID

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/servers/1/stdin

POST /api/v2/servers/<server_id>/stdin

Example Request Body

say the server will restart in 5 minutes

Example response bodies:

{
    "status": "ok"
}

Get a server's logs

Response data in practice	The server's data
Permission(s) required	Server permission `LOGS`
URL `server_id` placeholder	The server's ID
URL `file` query parameter	Whether to read the log file or stdout. Defaults to `false`
URL `colors` query parameter	Whether to add HTML coloring or not. Defaults to `false`
URL `raw` query parameter	Whether to disable ANSI stripping or not. Defaults to `false`
URL `html` query parameter	Whether to output in HTML with `<br/>`'s or with the standard API JSON format with an array of lines. Defaults to `false`

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/logs

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/logs\?raw\=true\&file\=true

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/logs\?colors\=true\&html\=true

GET /api/v2/servers/<server_id>/logs

Example response bodies:

{
    "status": "ok",
    "data": [
        "Picked up _JAVA_OPTIONS: -Dawt.useSystemAAFontSettings=on -Dswing.aatext=true -Djava.util.prefs.userRoot=&quot;$XDG_CONFIG_HOME&quot;/java",
        "Starting org.bukkit.craftbukkit.Main",
        "System Info: Java 18 (OpenJDK 64-Bit Server VM 18.0.1.1+2) Host: Linux 5.17.9-arch1-1 (amd64)",
        "Loading libraries, please wait...",
        "2022-05-25 18:27:53,400 ServerMain WARN Advanced terminal features are not available in this environment",
        "[18:27:55 INFO]: Environment: authHost=&#x27;https://authserver.mojang.com&#x27;, accountsHost=&#x27;https://api.mojang.com&#x27;, sessionHost=&#x27;https://sessionserver.mojang.com&#x27;, servicesHost=&#x27;https://api.minecraftservices.com&#x27;, name=&#x27;PROD&#x27;",
        "[18:27:56 INFO]: Loaded 7 recipes",
        "[18:27:57 INFO]: Starting minecraft server version 1.18.2",
        "[18:27:57 INFO]: Loading properties",
        "[18:27:57 INFO]: This server is running Paper version git-Paper-344 (MC: 1.18.2) (Implementing API version 1.18.2-R0.1-SNAPSHOT) (Git: 31ccc57)",
        "[18:27:57 INFO]: Server Ping Player Sample Count: 12",
        "[18:27:57 INFO]: Using 4 threads for Netty based IO",
        "[18:27:57 INFO]: Default game type: SURVIVAL",
        "[18:27:57 INFO]: Generating keypair",
        "[18:27:57 INFO]: Starting Minecraft server on *:25565",
        "[18:27:57 INFO]: Using epoll channel type",
        "[18:27:57 INFO]: Paper: Using libdeflate (Linux x86_64) compression from Velocity.",
        "[18:27:57 INFO]: Paper: Using OpenSSL 1.1.x (Linux x86_64) cipher from Velocity.",
        "[18:27:57 INFO]: Server permissions file permissions.yml is empty, ignoring it",
        "[18:27:57 INFO]: Preparing level &quot;world&quot;",
        "[18:27:58 INFO]: Preparing start region for dimension minecraft:overworld",
        "[18:27:58 INFO]: Time elapsed: 157 ms",
        "[18:27:58 INFO]: Preparing start region for dimension minecraft:the_nether",
        "[18:27:58 INFO]: Time elapsed: 56 ms",
        "[18:27:58 INFO]: Preparing start region for dimension minecraft:the_end",
        "[18:27:58 INFO]: Time elapsed: 90 ms",
        "[18:27:58 INFO]: Running delayed init tasks",
        "[18:27:58 INFO]: Done (1.170s)! For help, type &quot;help&quot;",
        "[18:27:58 INFO]: Timings Reset"
    ]
}

{
    "status": "ok",
    "data": [
        "[18:27:55] [ServerMain/INFO]: Environment: authHost='https://authserver.mojang.com', accountsHost='https://api.mojang.com', sessionHost='https://sessionserver.mojang.com', servicesHost='https://api.minecraftservices.com', name='PROD'",
        "[18:27:56] [Worker-Main-3/INFO]: Loaded 7 recipes",
        "[18:27:57] [Server thread/INFO]: Starting minecraft server version 1.18.2",
        "[18:27:57] [Server thread/INFO]: Loading properties",
        "[18:27:57] [Server thread/INFO]: This server is running Paper version git-Paper-344 (MC: 1.18.2) (Implementing API version 1.18.2-R0.1-SNAPSHOT) (Git: 31ccc57)",
        "[18:27:57] [Server thread/INFO]: Server Ping Player Sample Count: 12",
        "[18:27:57] [Server thread/INFO]: Using 4 threads for Netty based IO",
        "[18:27:57] [Server thread/INFO]: Default game type: SURVIVAL",
        "[18:27:57] [Server thread/INFO]: Generating keypair",
        "[18:27:57] [Server thread/INFO]: Starting Minecraft server on *:25565",
        "[18:27:57] [Server thread/INFO]: Using epoll channel type",
        "[18:27:57] [Server thread/INFO]: Paper: Using libdeflate (Linux x86_64) compression from Velocity.",
        "[18:27:57] [Server thread/INFO]: Paper: Using OpenSSL 1.1.x (Linux x86_64) cipher from Velocity.",
        "[18:27:57] [Server thread/INFO]: Server permissions file permissions.yml is empty, ignoring it",
        "[18:27:57] [Server thread/INFO]: Preparing level \"world\"",
        "[18:27:58] [Server thread/INFO]: Preparing start region for dimension minecraft:overworld",
        "[18:27:58] [Server thread/INFO]: Time elapsed: 157 ms",
        "[18:27:58] [Server thread/INFO]: Preparing start region for dimension minecraft:the_nether",
        "[18:27:58] [Server thread/INFO]: Time elapsed: 56 ms",
        "[18:27:58] [Server thread/INFO]: Preparing start region for dimension minecraft:the_end",
        "[18:27:58] [Server thread/INFO]: Time elapsed: 90 ms",
        "[18:27:58] [Server thread/INFO]: Running delayed init tasks",
        "[18:27:58] [Server thread/INFO]: Done (1.170s)! For help, type \"help\"",
        "[18:27:58] [Server thread/INFO]: Timings Reset"
    ]
}

Picked up _JAVA_OPTIONS: -Dawt.useSystemAAFontSettings=on -Dswing.aatext=true -Djava.util.prefs.userRoot=&quot;$XDG_CONFIG_HOME&quot;/java<br />Starting org.bukkit.craftbukkit.Main<br />System Info: Java 18 (OpenJDK 64-Bit Server VM 18.0.1.1+2) Host: Linux 5.17.9-arch1-1 (amd64)<br />Loading libraries, please wait...<br />2022-05-25 18:27:53,400 ServerMain WARN Advanced terminal features are not available in this environment<br /><span class="mc-log-info">[18:27:55 INFO]</span>: Environment: authHost=&#x27;https://authserver.mojang.com&#x27;, accountsHost=&#x27;https://api.mojang.com&#x27;, sessionHost=&#x27;https://sessionserver.mojang.com&#x27;, servicesHost=&#x27;https://api.minecraftservices.com&#x27;, name=&#x27;PROD&#x27;<br /><span class="mc-log-info">[18:27:56 INFO]</span>: Loaded 7 recipes<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Starting minecraft server version 1.18.2<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Loading properties<br /><span class="mc-log-info">[18:27:57 INFO]</span>: This server is running Paper version git-Paper-344 (MC: 1.18.2) (Implementing API version 1.18.2-R0.1-SNAPSHOT) (Git: 31ccc57)<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Server Ping Player Sample Count: 12<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Using 4 threads for Netty based IO<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Default game type: SURVIVAL<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Generating keypair<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Starting Minecraft server on *:25565<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Using epoll channel type<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Paper: Using libdeflate (Linux x86_64) compression from Velocity.<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Paper: Using OpenSSL 1.1.x (Linux x86_64) cipher from Velocity.<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Server permissions file permissions.yml is empty, ignoring it<br /><span class="mc-log-info">[18:27:57 INFO]</span>: Preparing level &quot;world&quot;<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Preparing start region for dimension minecraft:overworld<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Time elapsed: 157 ms<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Preparing start region for dimension minecraft:the_nether<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Time elapsed: 56 ms<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Preparing start region for dimension minecraft:the_end<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Time elapsed: 90 ms<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Running delayed init tasks<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Done (1.170s)! For <span class="mc-log-keyword">help</span>, type &quot;<span class="mc-log-keyword">help</span>&quot;<br /><span class="mc-log-info">[18:27:58 INFO]</span>: Timings Reset<br />

Get a server's public data

Response data in practice	The server's public data
Permission(s) required	Logged in
URL `server_id` placeholder	The server's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/public

GET /api/v2/servers/<server_id>/public

Example response body:

{
    "status": "ok",
    "data": {
        "server_id": 1,
        "created": "2022-05-25T01:24:22.427327",
        "server_name": "aaaaaaaaaaaaaaaa",
        "type": "minecraft-java"
    }
}

Get a server's statistics

Response data in practice	The server's statistics
Permission(s) required	Access to the server
URL `server_id` placeholder	The server's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/stats

GET /api/v2/servers/<server_id>/stats

Example response body:

{
    "status": "ok",
    "data": {
        "stats_id": 457,
        "created": "2022-05-25T18:47:41.814015",
        "server_id": {
            "server_id": 1,
            "created": "2022-05-25T01:24:22.427327",
            "server_uuid": "6079f8b1-d690-4974-9c0d-792480307a86",
            "server_name": "aaaaaaaaaaaaaaaa",
            "path": "/home/luukas/dev/crafty-commander/servers/6079f8b1-d690-4974-9c0d-792480307a86",
            "backup_path": "/home/luukas/dev/crafty-commander/backups/6079f8b1-d690-4974-9c0d-792480307a86",
            "executable": "paper-1.18.2.jar",
            "log_path": "/home/luukas/dev/crafty-commander/servers/6079f8b1-d690-4974-9c0d-792480307a86/logs/latest.log",
            "execution_command": "java -Xms1000M -Xmx2000M -jar /home/luukas/dev/crafty-commander/servers/6079f8b1-d690-4974-9c0d-792480307a86/paper-1.18.2.jar nogui",
            "auto_start": false,
            "auto_start_delay": 10,
            "crash_detection": false,
            "stop_command": "stop",
            "executable_update_url": "",
            "server_ip": "127.0.0.1",
            "server_port": 25565,
            "logs_delete_after": 0,
            "type": "minecraft-java"
        },
        "started": "2022-05-25 15:44:05",
        "running": true,
        "cpu": 0.33,
        "mem": "1.6GB",
        "mem_percent": 10.0,
        "world_name": "aaaaaaaaaaaaaaaa",
        "world_size": "185.4MB",
        "server_port": 25565,
        "int_ping_results": "True",
        "online": 0,
        "max": 20,
        "players": "[]",
        "desc": "A Minecraft Server",
        "version": "Paper 1.18.2",
        "updating": false,
        "waiting_start": false,
        "first_run": true,
        "crashed": false,
        "downloading": false
    }
}

Get everyone with access to a server

Response data in practice	The users with access to the server
Permission(s) required	Access to the server, Crafty permission `USER_CONFIG` and Crafty permission `ROLES_CONFIG`
URL `server_id` placeholder	The server's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/users

GET /api/v2/servers/<server_id>/users

Example response body:

{
    "status": "ok",
    "data": [
        1,
        3
    ]
}

Create a Schedule For a Server

Response data in practice	The new schedule's ID
Permission(s) required	Crafty permission `SCHEDULE`
JSON schema	`new_task`

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/servers/1/tasks/

POST /api/v2/servers/<server_id>/tasks/

Example request body:

{ 
    "name": "Test 1234",
    "enabled": true,
    "action": "custom_command",
    "interval": 1,
    "interval_type": "minutes",
    "command": "say hello world",
    "parent": null,
    "one_time": false,
    "cron_string": "",
    "delay": 0
}

Example response body:

{
    "status": "ok",
    "data": {
        "schedule_id": "3"
    }
}

Modify a Schedule For a Server

Response data in practice	none
Permission(s) required	Crafty permission `SCHEDULE`
JSON schema	`patch_task`

XH example(s):

xh -A bearer -a "$token" PATCH https://localhost:8443/api/v2/servers/1/tasks/1

PATCH /api/v2/servers/<server_id>/tasks/<task_id>

Example request body:

{ 
    "name": "Test 5678",
    "enabled": false,
}

Example response body:

{
    "status": "ok",
}

Remove A Schedule

Response data in practice	none
Permission(s) required	Crafty permission `SCHEDULE`

XH example(s):

xh -A bearer -a "$token" DELETE https://localhost:8443/api/v2/servers/1/tasks/1

DELETE /api/v2/servers/<server_id>/tasks/<task_id>

Example response body:

{
    "status": "ok",
}

Create A Server Webhook

Response data in practice	Webhook ID
Permission(s) required	Crafty permission `CONFIG`
JSON Schema	create_webhook

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/servers/1/webhook/

POST /api/v2/servers/<server_id>/webhook/

Example request body:

{
    "webhook_type": "Discord",
    "name": "My example Webhook",
    "url": "https://webhook.url.com",
    "bot_name": "Crafty BOT",
    "trigger": ["server_start"],
    "body": "Server Has Started",
    "enabled": true
}

Example response body:

{
    "status": "ok",
    "data": {
        "webhook_id": 1,
     },
}

Modify A Server Webhook

Response data in practice	Webhook ID
Permission(s) required	Crafty permission `CONFIG`
JSON Schema	patch_webhook

XH example(s):

xh -A bearer -a "$token" PATCH https://localhost:8443/api/v2/servers/1/webhook/1/

PATCH /api/v2/servers/<server_id>/webhook/<webhook_id>/

Example request body:

{
    "webhook_type": "Slack"
}

Example response body:

{
    "status": "ok",
}

Test A Server Webhook

Response data in practice	Webhook ID
Permission(s) required	Crafty permission `CONFIG`

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/servers/1/webhook/1/

POST /api/v2/servers/<server_id>/webhook/<webhook_id>/

Example response body:

{
    "status": "ok",
}

Get All Server Webhooks

Response data in practice	Webhook ID
Permission(s) required	Crafty permission `CONFIG`

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/webhook/

GET /api/v2/servers/<server_id>/webhook/

Example response body:

{
    "status": "ok",
    "data": {
        "1": {
            "webhook_type": "Discord",
            "name": "My example webhook",
            "url": "https://webhook.example.com",
            "bot_name": "BIG BOT",
            "trigger": "server_start,",
            "body": "Box was started\n",
            "enabled": true
        },
        "2": {
            "webhook_type": "Discord",
            "name": "test",
            "url": "https://webhook.example.com",
            "bot_name": "Crafty Controller",
            "trigger": "server_backup,",
            "body": "test1243\n",
            "enabled": false
        }
    }
}

Get Webhook

Response data in practice	Webhook ID
Permission(s) required	Crafty permission `CONFIG`

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/servers/1/webhook/3/

GET /api/v2/servers/<server_id>/webhook/<webhook_id>

Example response body:

{
    "status": "ok",
    "data": {
        "2": {
            "webhook_type": "Discord",
            "name": "test",
            "url": "https://webhook.example.com",
            "bot_name": "Crafty Controller",
            "trigger": "server_backup,",
            "body": "test1243\n",
            "enabled": false
        }
    }
}

Delete Webhooks

Response data in practice	Webhook ID
Permission(s) required	Crafty permission `CONFIG`

XH example(s):

xh -A bearer -a "$token" DELETE https://localhost:8443/api/v2/servers/1/webhook/3/

DELETE /api/v2/servers/<server_id>/webhook/<webhook_id>

Example response body:

{
    "status": "ok",
}

User requests

Get all the users

Response data in practice	All of the users
Permission(s) required	Crafty permission `USER_CONFIG`

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/users

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/users\?ids\=true

GET /api/v2/users

GET /api/v2/users?ids=true

Example response body for the path /api/v2/users:

{
    "status": "ok",
    "data": [
        {
            "user_id": 1,
            "created": "05/18/2022, 01:43:56",
            "username": "admin",
            "enabled": true,
            "superuser": true,
            "lang": "en_EN"
        }
    ]
}

Example response body for the path /api/v2/users?ids=true:

{
    "status": "ok",
    "data": [
        1
    ]
}

Create a user

Response data in practice	The new user's ID
Permission(s) required	Crafty permission `USER_CONFIG`
JSON schema	`new_user`

XH example(s):

xh -A bearer -a "$token" POST https://localhost:8443/api/v2/users -- username='test' password='test' email='[email protected]' lang='fi_FI' superuser:='true'

POST /api/v2/users

Example request body:

{
    "username": "test",
    "password": "test",
    "manager": "1", (manager's user id)
    "email": "[email protected]",
    "lang": "fi_FI",
    "superuser": true,
    "theme": "dark",
}

Example response body:

{
    "status": "ok",
    "data": {
        "user_id": "3"
    }
}

Get a user

Response data in practice	The user's data
Permission(s) required	Crafty permission `USER_CONFIG` if you aren't viewing yourself
URL `user_id` placeholder	The user's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/users/3

GET /api/v2/users/<user_id>

Example response body:

{
    "status": "ok",
    "data": {
        "user_id": 3,
        "created": "05/24/2022, 09:44:33",
        "last_login": "2022-05-24T09:44:33.646325",
        "last_update": "05/24/2022, 09:44:33",
        "last_ip": "",
        "username": "test",
        "email": "[email protected]",
        "enabled": true,
        "superuser": true,
        "lang": "fi_FI",
        "support_logs": "",
        "server_order": "",
        "preparing": false,
        "hints": true,
        "roles": [
            {
                "role_id": 1,
                "created": "05/24/2022, 09:55:43",
                "last_update": "2022-05-24T09:55:43.373545",
                "role_name": "my testing role"
            }
        ]
    }
}

Delete a user

Response data in practice	Nothing important
Permission(s) required	Crafty permission `USER_CONFIG` if you aren't deleting yourself and the `allow_self_delete` config option is on
URL `user_id` placeholder	The user's ID

XH example(s):

xh -A bearer -a "$token" DELETE https://localhost:8443/api/v2/users/3

DELETE /api/v2/users/<user_id>

Example response body:

{
    "status": "ok"
}

Modify a user

Response data in practice	Nothing important
Permission(s) required	Crafty permission `USER_CONFIG` if you aren't modifying yourself
JSON schema	`user_patch`
URL `user_id` placeholder	The user's ID

XH example(s):

xh -A bearer -a "$token" PATCH https://localhost:8443/api/v2/users/3 -- username='johnsmith' roles:='[1]'

PATCH /api/v2/users/<user_id>

Example request body:

{
    "username": "johnsmith",
    "roles": [1]
}

Example response body: <syntaxhighlight lang="json> { {{__snippet|post|153|pre}} } </syntaxhighlight>

<h3>Get a user's Crafty permissions

Response data in practice	The user's Crafty permission data including the counters and limits
Permission(s) required	Crafty permission `USER_CONFIG` if you aren't viewing yourself
URL `user_id` placeholder	The user's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/users/3/permissions

GET /api/v2/users/<user_id>/permissions

Example response body:

{
    "status": "ok",
    "data": {
        "permissions": "110",
        "counters": {
            "SERVER_CREATION": 3,
            "USER_CONFIG": 0,
            "ROLES_CONFIG": 0
        },
        "limits": {
            "SERVER_CREATION": 5,
            "USER_CONFIG": 0,
            "ROLES_CONFIG": 0
        }
    }
}

Get a user's profile picture

Response data in practice	The user's public data
Permission(s) required	Logged in
URL `user_id` placeholder	The user's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/users/3/pfp

GET /api/v2/users/<user_id>/pfp

Example response body:

{
    "status": "ok",
    "data": "https://www.gravatar.com/avatar/93431c5d5a2b6a10ab3d5106d44d5590?default=404&rating=g"
}

Get a user's public data

Response data in practice	The user's public data
Permission(s) required	Logged in
URL `user_id` placeholder	The user's ID

XH example(s):

xh -A bearer -a "$token" GET https://localhost:8443/api/v2/users/3/public

GET /api/v2/users/<user_id>/public

Example response body:

{
    "status": "ok",
    "data": {
        "user_id": 3,
        "created": "05/24/2022, 09:44:33",
        "username": "test",
        "enabled": true,
        "superuser": true,
        "lang": "fi_FI",
        "roles": []
    }
}

Crafty requests

Modify Config.json

Response data in practice	Nothing important
Permission(s) required	Superuser
JSON schema	`config_json_schema`

PATCH /api/v2/crafty/config

Example request body:

{
    "http_port": 8000,
    "https_port": 8443,
    "keywords": [
        "help",
        "chunk",
        "joined"
    ],

}

Example response body:

{
    "status": "ok",
}

Folder: docs

Contents

Introduction

Important information

XH examples

Example request in raw HTTP

JSON schemas

API V2 Endpoints

Authentication requests

Log out every single session the token's user has

Log in and get a token

Role requests

Get all the roles

Create a role

Get a role

Get a role's servers

Get a role's users

Delete a role

Modify a role

Get all the servers

Create a server

Get a server

Delete a server

Modify a server

Send an action to a server

Send a STDIn command to a server

Get a server's logs

Get a server's public data

Get a server's statistics

Get everyone with access to a server

Create a Schedule For a Server

Modify a Schedule For a Server

Remove A Schedule

Create A Server Webhook

Modify A Server Webhook

Test A Server Webhook

Get All Server Webhooks

Get Webhook

Delete Webhooks

User requests

Get all the users

Create a user

Get a user

Delete a user

Modify a user

Get a user's profile picture

Get a user's public data

Crafty requests

Modify Config.json