Skip to content

API Reference ​

Utopia Server Panel exposes a complete HTTP REST API and WebSocket real-time channel supporting Personal API Access Tokens for automation scripts, external monitoring, and third-party integrations.

Authentication & Token Format ​

Logged-in users can create Personal API Access Tokens under Personal Settings -> API Tokens. Tokens start with the usp_ prefix and are displayed in full only once upon creation; only their SHA-256 hash is stored in the database.

Pass the token in the Authorization header for HTTP requests:

http
Authorization: Bearer usp_your_token_here

For WebSocket connections to /ws, send an authentication frame after connecting:

json
{
  "action": "auth",
  "token": "usp_your_token_here"
}

Scopes & Permission Rules ​

The effective permissions of an API token are the intersection of the owner's role permissions and the token's scopes:

  • A token with scope * inherits all permissions of the owning account.
  • A token with restricted scopes such as dashboard:1,terminal:2 can only access matching modules up to the specified level.
  • Sensitive account credential and binding mutations, including non-GET requests under /api/me/* and /api/binding/*, strictly require * scope and return INSUFFICIENT_SCOPE for restricted tokens.

HTTP Endpoints ​

Below are the endpoints accessible with an API Access Token, grouped by module.

Profile & Self-Service ​

MethodPathPermission or ScopeDescription
GET/api/meAuthenticated; restricted tokens need profile:1 or readGet current account info and permission matrix
GET/api/me/sessionsSame as aboveList active login sessions
GET/api/me/login-historySame as aboveRetrieve the latest 20 login audit entries
GET/api/me/tokensSame as aboveList API token metadata for the current user
POST/api/me/tokens* scope onlyCreate a new API access token
DELETE/api/me/tokens/{id}* scope onlyRevoke an API access token
GET/api/binding/listAuthenticated; restricted tokens need profile:1 or readList bound Minecraft characters
GET/api/player/meSame as aboveFetch live in-game data for the primary bound player

Server Status & Monitoring ​

MethodPathPermission or ScopeDescription
GET/api/statusdashboard:1Get live server status, TPS, MSPT, players, and system resources
GET/api/monitor/configPublic or authenticatedGet monitoring display configuration
GET/api/monitor/perflogs:1Query historical performance samples
GET/api/monitor/playerslogs:1Query player join and leave events
GET/api/monitor/lifecyclelogs:1Query paginated server lifecycle records
GET/api/monitor/lifecycle/rangelogs:1Query server lifecycle records within a time range

Performance Profiler & Web Minimap ​

MethodPathPermission or ScopeDescription
GET/api/profiler/snapshotprofiler:1Get current dimension tick breakdown and chunk hotspots
POST/api/profiler/teleportprofiler:2Teleport bound player to hotspot coordinates
GET/api/map/bootstrapmap:1Get minimap configuration, dimensions, and permissions
GET/api/map/tilemap:1Fetch a map tile image for a dimension and zoom level
GET/api/map/regionsmap:1List available or rendered region coordinates
GET/api/map/overlaysmap:1Fetch live players, mobs, entities, and waypoint overlays
POST/api/map/waypointsmap:2Create a map waypoint
DELETE/api/map/waypoints/{id}map:2Delete a map waypoint
POST/api/map/teleportmap:1 and map teleport settingTeleport bound player to map coordinates
POST/api/map/reset-healthadmin:2Reset minimap renderer health state
POST/api/map/clear-cacheadmin:2Clear minimap disk tile cache

Mods & Server Config ​

MethodPathPermission or ScopeDescription
GET/api/mods/overviewmods_config:1List installed mods and config file tree
GET/api/mods/configmods_config:1Read a mod configuration file
PUT/api/mods/configmods_config:2Save edits to a mod configuration file
GET/api/mods/server-propertiesmods_config:1Read server.properties
PUT/api/mods/server-propertiesmods_config:2Save changes to server.properties
POST/api/mods/restartmods_config:2Trigger the configured server restart command

Whitelist & Messaging ​

MethodPathPermission or ScopeDescription
GET/api/whitelist/admin/applicationswhitelist_manage:1List whitelist applications
POST/api/whitelist/admin/applications/{id}/reviewwhitelist_manage:2Approve or reject a whitelist application
GET/api/whitelist/admin/entrieswhitelist_manage:1List current server whitelist entries
POST/api/whitelist/admin/entrieswhitelist_manage:2Manually add a whitelist entry
DELETE/api/whitelist/admin/entries/{name}whitelist_manage:2Manually remove a whitelist entry
GET/api/messages/inboxAuthenticated; restricted tokens need messages:1 or chat:1List inbox messages
GET/api/messages/sentSame as aboveList sent messages
GET/api/messages/unread-countSame as aboveGet unread message count
POST/api/messages/sendAuthenticated; restricted tokens need messages:2 or chat:2Send an in-site message
POST/api/messages/read-allSame as aboveMark all inbox messages as read
POST/api/messages/{id}/readSame as aboveMark a single message as read
GET/api/chat/historyAuthenticated; restricted tokens need chat:1 or messages:1Fetch synced in-game chat history
POST/api/chat/sendAuthenticated; restricted tokens need chat:2 or messages:2Send a chat message into the Minecraft server

Administration ​

MethodPathPermission or ScopeDescription
GET/api/admin/usersadmin:1List all panel users
POST/api/admin/usersadmin:2Create a new user
PATCH/api/admin/users/{id}admin:2Update user info or status
DELETE/api/admin/users/{id}admin:2Delete a user
POST/api/admin/users/{id}/unbindadmin:2Unbind a user's Minecraft player
POST/api/admin/users/{id}/reset-2faadmin:2Reset a user's 2FA configuration
POST/api/admin/users/{id}/unlockadmin:2Unlock a locked-out account
GET/api/admin/rolesadmin:1List all roles
GET/api/admin/roles/{id}admin:1Get role details and permission matrix
POST/api/admin/rolesadmin:2Create a custom role
PUT/api/admin/roles/{id}admin:2Update role permissions
DELETE/api/admin/roles/{id}admin:2Delete a custom role
GET/api/admin/permissionsadmin:1List all permission definitions
GET/api/admin/settingsadmin:1Get global system settings
PATCH/api/admin/settingsadmin:2Update global system settings
GET/api/admin/worldsadmin:1List indexed saves and database stats

WebSocket Reference ​

After connecting to /ws and authenticating with an auth frame, the following action commands are supported:

ActionPermissionParametersDescription
authNonetokenAuthenticate or refresh the connection identity
fetch_statusdashboard:1NoneRequest a full server status JSON snapshot
fetch_logsterminal:1NoneFetch buffered console log lines
fetch_command_historyterminal:1NoneFetch executed command history
fetch_completionsterminal:1command, requestIdRequest Tab completion candidates
execute_commandterminal:2commandExecute a command on the server console

The server also pushes status_delta, new_log, and new_monitor_log events to authorized connections.

Example Request ​

Fetch live server status with curl:

bash
curl -s -H "Authorization: Bearer usp_your_token_here" \
  http://127.0.0.1:55533/api/status