API

MuteCloud speaks HTTP and WebSocket on the same address, by default 127.0.0.1:8770. Both live in mutecloud.toml:

mutecloud.toml

[api]
bind = "127.0.0.1:8770"
token = "..."

If the API binds to the outside without a token, the cloud warns on start. Without a token only callers from the same machine are allowed.

HTTP

A="Authorization: Bearer $TOKEN"
H="http://127.0.0.1:8770"
curl -H "$A" $H/api/services

Route	What it does	Right
`GET /api/health`	liveness, no token needed	—
`GET /api/openapi.json`	description of this API	—
`GET /api/status`	node, version, counts	—
`GET /api/nodes`	all nodes in the cluster	`groups.view`
`GET /api/groups`	all groups	`groups.view`
`GET /api/groups/{name}`	one group with its servers	`groups.view`
`POST /api/groups/{name}/{action}`	start, stop, restart, rollout, disable, backup	depends
`GET /api/services`	running servers	`service.view`
`GET /api/services/{id}`	one server	`service.view`
`GET /api/services/{id}/logs`	recent log lines	`service.view`
`POST /api/services/{id}/{action}`	stop, drain, restart	depends
`POST /api/services/{id}/exec`	a command to that server's console	`service.console`
`GET /api/players`	who is online	`players.view`
`GET /api/players/{name}`	a single player	`players.view`
`GET /api/ranks`	ranks	`ranks.view`
`GET /api/ranks/{player}`	a player's rights	`ranks.view`
`GET /api/data/{namespace}`	shared storage	`data.view`
`GET PUT DELETE /api/data/{namespace}/{key}`	one entry	`data.view` / `data.edit`
`POST /api/announce`	broadcast to all players	`announce`
`POST /api/maintenance`	toggle maintenance	`maintenance`
`GET /api/layers`	templates with their revision	`layers.read`
`GET /api/layers/{name}`	a template as tar.gz	`layers.read`
`GET /api/update`	version and whether a newer one waits	`groups.view`
`POST /api/command`	any command, answer as lines	depends

Missing a right gives 403 and names the right that was missing. After eight wrong tokens an address is locked out for a minute.

curl -H "$A" -X POST $H/api/groups/Lobby/start
curl -H "$A" -X POST -H 'Content-Type: application/json' \
     -d '{"line":"say Restart in 5 minutes"}' $H/api/services/Lobby-1/exec
curl -H "$A" -X POST -H 'Content-Type: application/json' \
     -d '{"message":"&bBack in a moment","title":true}' $H/api/announce

The complete description is served at /api/openapi.json, which allows clients to be generated or the routes to be imported into tools such as Postman or Insomnia.

Tokens

token create website groups.view players.view
token list
token delete website

A token receives only the rights it requires. * grants full access and should not be handed to a web frontend.

WebSocket

ws://127.0.0.1:8770/ws carries the same protocol the bridges use. After connecting you send:

{"t":"hello","d":{"version":1,"role":"operator","token":"..."}}

From then on events arrive as they happen: snapshot, service_update, service_gone, log, network, permissions, node_info. To control things you send command and the answer comes back as output with the same request id.

This is the appropriate interface for a web frontend or a bot that should receive events instead of polling.

For plugins

The bridge is deployed to every server and exposes a small API:

MuteCloud.services();                    // every server in the network
MuteCloud.services("Lobby");             // one group
MuteCloud.best("Lobby");                 // the emptiest one accepting players
MuteCloud.send(player, "Lobby");         // move a player
MuteCloud.networkPlayers();              // players across the network
MuteCloud.data("myplugin").set(k, v);    // shared storage

Plus placeholders such as %mutecloud_service%, %mutecloud_network_players% and %mutecloud_players_lobby% once PlaceholderAPI is installed.

HTTP

Tokens

WebSocket

For plugins

On this page