API V2

Contents

Introduction

Important information

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",
    "email": "[email protected]",
    "lang": "fi_FI",
    "superuser": true
}

JSON schemas

Here is a list of available JSON schemas at commit 4c64497a2f4dd60c086215ad0962649b40f2d835:

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/invalidate_tokens

POST /api/v2/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:

{
    "status": "ok"
}

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": {"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" PATCH https://localhost:8443/api/v2/servers/1/start_server

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

Example response bodies:

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

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="$XDG_CONFIG_HOME"/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='https://authserver.mojang.com', accountsHost='https://api.mojang.com', sessionHost='https://sessionserver.mojang.com', servicesHost='https://api.minecraftservices.com', name='PROD'",
        "[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 "world"",
        "[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 "help"",
        "[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="$XDG_CONFIG_HOME"/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='https://authserver.mojang.com', accountsHost='https://api.mojang.com', sessionHost='https://sessionserver.mojang.com', servicesHost='https://api.minecraftservices.com', name='PROD'<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 "world"<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 "<span class="mc-log-keyword">help</span>"<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 <code>{{__snippet|post|13|nowiki}}</code>

Example response body:
<pre>
{
    "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 <code>{{__snippet|post|12|nowiki}}</code>

Example response body:
<pre>
{
    "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 <code>{{__snippet|post|11|nowiki}}</code>

Example response body:
<pre>
{
    "status": "ok",
    "data": [
        1,
        3
    ]
}

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",
    "email": "[email protected]",
    "lang": "fi_FI",
    "superuser": true
}

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:

{
    "status": "ok"
}

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": []
    }
}