API

Control MuteCloud from outside over HTTP and WebSocket, and from plugins through the bridge 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	none
`GET /api/openapi.json`	description of this API	none
`GET /api/status`	node, version, counts	any valid token
`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`
`GET /api/services/{id}/properties`	properties the server has set	`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, `PUT` takes the value as plain text body	`data.view` / `data.edit`
`POST /api/announce`	broadcast to all players	`announce`
`POST /api/channels/{channel}`	message to plugins, optionally with `target`	`channels.publish`
`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
`GET /metrics`	Prometheus text, see metrics	`groups.view`

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. Channel messages arrive as message once you have registered with listen, and with publish you send your own.

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 an API, plus properties, channels between servers and events for Paper and Velocity. All of it is described under plugins.

MuteCloud.best("Lobby");                          // the emptiest one accepting players
MuteCloud.send(player, "Lobby");                  // move a player
MuteCloud.setState("INGAME");                     // property of this server
MuteCloud.channel("party").publish(invite);       // message to other servers
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.

HTTPCopy Anchor Link

TokensCopy Anchor Link

WebSocketCopy Anchor Link

For pluginsCopy Anchor Link

On this page

HTTP

Tokens

WebSocket

For plugins