Remote Control API
When Remote Control is active, PocketMC runs an embedded ASP.NET Core Kestrel web server on port 25580. It serves the bundled web dashboard and provides a REST and WebSocket API
for controlling your Minecraft servers programmatically.
http://127.0.0.1:25580 · Authentication: Cookie session via POST /api/loginAuthentication and Sessions
To interact with protected API endpoints, authenticate with your administrator or sub-user credentials at /api/login.
Upon successful authentication, the server sets a session cookie named PocketMCRemoteAuth.
POST /api/login HTTP/1.1 Host: 127.0.0.1:25580 Content-Type: application/json { "username": "admin", "password": "your-password" }
HTTP/1.1 200 OK Set-Cookie: PocketMCRemoteAuth=...; path=/; samesite=strict; httponly; max-age=86400 { "success": true }
The login endpoint limits requests to 5 failed attempts per minute per IP address. Exceeding this rate returns HTTP 429.
Daemon Status and Permissions
Query server status, network endpoints, and the active session's permission flags:
GET /api/status HTTP/1.1 Cookie: PocketMCRemoteAuth=...
{ "enabled": true, "hostRunning": true, "port": 25580, "accessMode": 0, "localUrls": ["http://127.0.0.1:25580", "http://192.168.1.50:25580"], "publicUrl": null, "tunnelRunning": false, "allowRemoteConsoleCommands": true, "allowRemotePlayerActions": true, "allowRemoteServerSettings": true, "allowRemoteServerAddons": true, "allowRemoteFileManager": true, "allowRemoteServerBackups": true }
Instance Lifecycle Endpoints
Control server processes using their instance GUID:
| Method | Endpoint | Description |
|---|---|---|
GET | /api/instances | Lists all instances permitted for the current authenticated user account. |
GET | /api/instances/{id}/status | Returns runtime status, player counts, CPU percentage, and memory usage in bytes. |
POST | /api/instances/{id}/start | Spawns the server process within its Win32 Job Object sandbox. |
POST | /api/instances/{id}/stop | Sends graceful stop command with RCON save-flush before process exit. |
POST | /api/instances/{id}/restart | Executes a clean shutdown followed by an automatic reboot. |
Live Console and WebSockets
Terminal output can be retrieved through polling or live WebSocket streaming:
- Buffered Output:
GET /api/instances/{id}/console/historyreturns recent console output lines stored in the server's in-memory circular buffer. - Command Input:
POST /api/instances/{id}/console/commandsends a command to the server STDIN. Body format:{"command": "say Hello"}. Submissions are limited to 30 requests per minute per instance. - WebSocket Stream: Connect your WebSocket client to
/ws/instances/{id}/consolewith thePocketMCRemoteAuthsession cookie. PocketMC pushes log lines over the socket in real time and processes text messages sent over the socket as server commands.
Player Moderation and Settings
Manage players and configuration options remotely:
- Player List:
GET /api/instances/{id}/playersreturns online usernames and connection statistics. - Player Actions:
POST /api/instances/{id}/players/{name}/{action}executes moderation actions. Valid actions arekick,ban,pardon,op, anddeop. On Bedrock servers, ban commands update the internalpocketmc-bans.jsonsidecar. - Server Properties:
GET /api/instances/{id}/propertiesreturns current settings as a key-value object.PUT /api/instances/{id}/propertieswrites updated values back to theserver.propertiesfile.
Addons and Modifications
Manage plugins and mods over the API:
- List Addons:
GET /api/instances/{id}/addonslists installed plugins and mods, file sizes, and enabled states. - Uninstall Addon:
POST /api/instances/{id}/addons/uninstallremoves a mod or plugin file. Body format:{"fileName": "example.jar", "addonType": 0}.
Files and World Backups
Sandboxed filesystem access and backup controls:
- List Files:
GET /api/instances/{id}/files?path=pluginsreturns files and directories inside the specified path. Access outside the instance root directory is blocked. - Read Text File:
GET /api/instances/{id}/files/content?path=server.propertiesretrieves file text. Files larger than 1 MB are rejected to preserve memory. - Save Text File:
PUT /api/instances/{id}/files/contentwrites updated text back to disk. Body format:{"path": "server.properties", "content": "..."}. - Upload File:
POST /api/instances/{id}/files/uploadaccepts multipart form uploads up to 100 MB per file directly into the target directory. - Delete File:
DELETE /api/instances/{id}/files?path=...permanently removes the designated file or directory. - Backup History:
GET /api/instances/{id}/backupslists archive files with file size, creation timestamp, and SHA-256 integrity hash. - Create Backup:
POST /api/instances/{id}/backupsinitiates an immediate background snapshot with an automatic RCON save-flush if the server is running.