HomeDocsAPIV2 API Reference
API

V2 API Reference

REST API reference for all V2 endpoints.

bthavanishBy bthavanish

V2 API Reference

Base URL: /api/v2

All responses use a standard envelope:

// Success
{ "success": true, "data": <T>, "meta": <PaginationMeta?> }

// Error
{ "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found" } }

Pagination meta (snake_case):

{ "total": 100, "per_page": 25, "current_page": 1, "last_page": 4 }

Authentication

Two methods, applied per sub-router:

  • Session auth (standard browser session cookie)
  • API key auth (Authorization: Bearer <key> header)

API keys require scope capabilities (e.g., servers.*, files.read). Session users bypass capability checks.

Servers

MethodPathDescription
GET/serversList user’s servers (paginated)
GET/servers/:idGet server details
PATCH/servers/:idUpdate server (name, description, memory, cpu, storage, swap, backupLimit, databaseLimit)
DELETE/servers/:idDelete server
POST/servers/:id/powerPower action (`{ action: “start”
POST/servers/:id/reinstallReinstall server
GET/servers/:id/statusGet container status (&#123; online, status &#125;)

Admins see all servers. Regular users see servers they own or have sub-user access to.

Files

All file operations require files.read or files.write sub-user permission.

MethodPathDescription
GET/servers/:id/files?path=/List directory contents
GET/servers/:id/files/content?file=/pathRead file content
POST/servers/:id/files/contentWrite file (&#123; file, content &#125;)
DELETE/servers/:id/filesDelete file (&#123; file &#125;)
POST/servers/:id/files/renameRename file (&#123; file, newname &#125;)
POST/servers/:id/files/mkdirCreate directory (&#123; name &#125;)
POST/servers/:id/files/copyCopy file (&#123; file, target &#125;)
POST/servers/:id/files/zipZip files (&#123; files: [], target &#125;)
POST/servers/:id/files/unzipUnzip file (&#123; file, target? &#125;)
POST/servers/:id/files/pullGit pull

Databases

MethodPathDescription
GET/servers/:id/databasesList databases (paginated)
POST/servers/:id/databasesCreate database (&#123; hostId &#125;)
DELETE/servers/:id/databases/:dbIdDelete database
POST/servers/:id/databases/:dbId/rotateRotate password

Database names are auto-generated: s{uuid_prefix}_db{N}. Passwords are random 24-byte base64url strings.

Backups

MethodPathDescription
GET/servers/:id/backupsList backups (paginated)
POST/servers/:id/backupsCreate backup (&#123; name &#125;)
DELETE/servers/:id/backups/:backupIdDelete backup (fails if locked)
POST/servers/:id/backups/:backupId/restoreRestore backup
PATCH/servers/:id/backups/:backupId/lockToggle lock
GET/servers/:id/backups/:backupId/downloadDownload backup (streaming)
GET/servers/:id/backups/progressBackup progress
GET/servers/:id/backups/restore/progressRestore progress

Backup limit is per-server (default 5, configurable). Locked backups cannot be deleted.

Schedules

MethodPathDescription
GET/servers/:id/schedulesList schedules (paginated)
POST/servers/:id/schedulesCreate schedule (&#123; name, cron, action, payload?, enabled?, timeOffset? &#125;)
PATCH/servers/:id/schedules/:scheduleIdUpdate schedule
DELETE/servers/:id/schedules/:scheduleIdDelete schedule
POST/servers/:id/schedules/:scheduleId/tasksAdd task
DELETE/servers/:id/schedules/:scheduleId/tasks/:taskIdRemove task
POST/servers/:id/schedules/:scheduleId/runRun schedule now

Schedule actions: command, power, backup. Power payload must include a valid action: start, stop, restart, kill.

Sub-Users

MethodPathDescription
GET/servers/:id/subusersList sub-users (paginated)
POST/servers/:id/subusersAdd sub-user (&#123; userId, permissions[] &#125;)
PUT/servers/:id/subusers/:subIdUpdate permissions
DELETE/servers/:id/subusers/:subIdRemove sub-user

Only the server owner (or admin) can manage sub-users.

Startup

MethodPathDescription
GET/servers/:id/startupGet startup config (command, docker image, variables, image definition)
POST/servers/:id/startup/commandSave startup command (&#123; command &#125;), requires allowStartupEdit
POST/servers/:id/startup/docker-imageSave docker image (&#123; dockerImage &#125;), must be in image’s allowed list
POST/servers/:id/startup/variablesSave environment variables (&#123; variables: [&#123; key, value, editable?, rules? &#125;] &#125;)

Account

Session auth only. All endpoints under /api/v2/account.

MethodPathDescription
GET/accountGet current user profile
PATCH/account/usernameUpdate username (&#123; username &#125;)
PATCH/account/emailChange email (&#123; email &#125;)
PATCH/account/passwordChange password (&#123; currentPassword, newPassword &#125;)
PATCH/account/descriptionUpdate description
PATCH/account/preferred-nodeSet preferred node (&#123; nodeId &#125; or null)
PATCH/account/languageSet language preference
POST/account/avatarUpload avatar (multipart, JPEG/PNG/GIF/WebP, max 5MB)
DELETE/account/avatarRemove avatar
GET/account/check-username?username=...Check username availability
POST/account/validate-passwordValidate password strength (&#123; password &#125;)
GET/account/2fa/setupGet TOTP setup data (secret + otpauth URL)
POST/account/2fa/enableEnable 2FA (&#123; code &#125;), returns recovery codes
POST/account/2fa/disableDisable 2FA (&#123; code &#125; or &#123; recoveryCode &#125;)
POST/account/imagesCreate user image
POST/account/images/import-urlImport image from URL
DELETE/account/images/:idDelete user image
GET/account/foldersList folders with server members
POST/account/foldersCreate folder (&#123; name &#125;)
DELETE/account/folders/:idDelete folder
POST/account/folders/:id/serversAdd server to folder (&#123; serverUUID &#125;)
DELETE/account/folders/servers/:uuidRemove server from folder
POST/account/onboarding/completeMark onboarding complete
POST/account/onboarding/skipSkip onboarding

Passkeys (WebAuthn)

MethodPathDescription
POST/account/passkey/register/optionsGenerate registration challenge
POST/account/passkey/register/verifyVerify registration (&#123; credential, deviceName? &#125;)
POST/account/passkey/auth/optionsGenerate auth challenge (login 2FA)
POST/account/passkey/auth/verifyVerify auth assertion (completes login)
GET/account/passkeyList user’s passkeys
DELETE/account/passkey/:idRemove passkey

System

MethodPathDescription
GET/system/statusSystem status (version, counts, uptime)
GET/system/healthHealth check (database connectivity)
POST/system/test-nodeTest node connection (admin only)
GET/system/search?q=...Global search (servers, users, nodes, features)

Admin

All admin endpoints require admin session auth. Mounted under /api/v2/admin.

Nodes

MethodPathDescription
GET/admin/nodesList nodes (paginated)
GET/admin/nodes/listLightweight list for dropdowns
POST/admin/nodesCreate node
GET/admin/nodes/:idGet node
GET/admin/nodes/:id/configureGet daemon configure command
PUT/admin/nodes/:idUpdate node
DELETE/admin/nodes/:idDelete node (must have 0 servers)
POST/admin/nodes/:id/verifyVerify daemon connection
POST/admin/nodes/:id/maintenanceToggle maintenance mode
GET/admin/nodes/:id/statsGet node stats from daemon
GET/admin/nodes/:id/allocationsList port allocations
POST/admin/nodes/:id/allocationsAdd allocation (&#123; ip, port &#125;)
DELETE/admin/nodes/:id/allocations/:allocIdDelete allocation (must be unassigned)

Users

MethodPathDescription
GET/admin/usersList users (paginated, searchable)
POST/admin/usersCreate user
GET/admin/users/:idGet user
PUT/admin/users/:idUpdate user
DELETE/admin/users/:idDelete user (must have 0 servers, can’t delete self)
POST/admin/users/:id/transferTransfer server ownership (&#123; newOwnerId &#125;)
POST/admin/users/:id/onboarding/resetReset onboarding state

Servers (Admin)

MethodPathDescription
GET/admin/serversList all servers
POST/admin/serversCreate server (admin override)
GET/admin/servers/:idGet server
PUT/admin/servers/:idUpdate server
DELETE/admin/servers/:idDelete server
POST/admin/servers/:id/transferTransfer ownership

Settings

MethodPathDescription
GET/admin/settingsGet all settings
PATCH/admin/settings/generalUpdate general settings (title, description, logo, theme, registration, etc.)
PATCH/admin/settings/securityUpdate security settings (rate limiting, 2FA, reverse proxy, etc.)
PATCH/admin/settings/server-policyUpdate server policy (limits, defaults, user permissions)
PATCH/admin/settings/featuresUpdate feature toggles (SFTP, backups, schedules, console, etc.)
PATCH/admin/settings/smtpUpdate SMTP settings
POST/admin/settings/smtp/testTest SMTP connection
PATCH/admin/settings/s3Update S3 settings
POST/admin/settings/s3/testTest S3 connection
POST/admin/settings/ban-ipBan IP (&#123; ip, reason? &#125;)
POST/admin/settings/unban-ipUnban IP (&#123; ip &#125;)

Databases (Admin)

MethodPathDescription
GET/admin/databasesList database hosts
POST/admin/databasesCreate database host
GET/admin/databases/:idGet database host
DELETE/admin/databases/:idDelete database host
POST/admin/databases/:id/testTest connection

Images

MethodPathDescription
GET/admin/imagesList images (paginated)
GET/admin/images/listLightweight list for dropdowns
POST/admin/imagesCreate image
POST/admin/images/uploadUpload egg JSON file
POST/admin/images/import-urlImport egg from URL
GET/admin/images/store/catalogueImage store catalogue
POST/admin/images/store/refreshRefresh catalogue
POST/admin/images/store/installInstall from store
GET/admin/images/:idGet image
PUT/admin/images/:idUpdate image
POST/admin/images/:id/approveApprove pending image
POST/admin/images/:id/rejectReject pending image
DELETE/admin/images/:idDelete image

Roles

MethodPathDescription
GET/admin/rolesList roles (paginated, with user counts)
POST/admin/rolesCreate role
GET/admin/roles/:idGet role details
PUT/admin/roles/:idUpdate role
DELETE/admin/roles/:idDelete role (can’t delete system roles)

Locations

MethodPathDescription
GET/admin/locationsList locations
POST/admin/locationsCreate location (&#123; name, shortCode &#125;)
PUT/admin/locations/:idUpdate location
DELETE/admin/locations/:idDelete location

Mounts

MethodPathDescription
GET/admin/mountsList mounts
POST/admin/mountsCreate mount (&#123; name, source, target, readOnly? &#125;)
DELETE/admin/mounts/:idDelete mount

API Keys

MethodPathDescription
GET/admin/apikeysList API keys
POST/admin/apikeysCreate API key
PUT/admin/apikeys/:idUpdate API key
DELETE/admin/apikeys/:idDelete API key
POST/admin/apikeys/:id/toggleToggle active state

Addons

MethodPathDescription
GET/admin/addonsList addons
POST/admin/addons/:slug/toggleEnable/disable addon
POST/admin/addons/:slug/reloadReload addon
POST/admin/addons/:slug/uninstallUninstall addon

Overview

MethodPathDescription
GET/admin/overview/check-updateCheck for panel updates
POST/admin/overview/perform-updatePerform panel update

Radar (Security Scanner)

MethodPathDescription
POST/admin/radar/scan/:serverIdScan server files
GET/admin/radar/virustotal-enabledCheck VirusTotal config
GET/admin/radar/scriptsList available scan scripts
POST/admin/radar/vtscan/:serverIdVirusTotal scan
POST/admin/radar/virustotalRun VirusTotal check

Analytics

MethodPathDescription
GET/admin/analytics/summaryAnalytics summary

Player Stats

MethodPathDescription
GET/admin/playerstatsGet player stats history
POST/admin/playerstats/collectTrigger stats collection

API Key Capabilities

API keys declare a set of scope capabilities. Wildcard forms grant all sub-capabilities.

CapabilityGrants
servers.*All server operations
servers.readRead servers
servers.writeUpdate/delete servers
files.*All file operations
files.readRead files
files.writeWrite/delete files
databases.*All database operations
backups.*All backup operations
schedules.*All schedule operations
subusers.*All sub-user operations
startup.*All startup operations
account.*Account operations
admin.*All admin operations

Sub-User Permissions

Sub-user permissions are granted per-server by the server owner:

PermissionDescription
consoleView console
console.sendSend commands to console
filesAll file operations
files.readRead files
files.writeWrite/delete files
backupsView backups
backups.createCreate backups
backups.deleteDelete backups
schedule.readView schedules
schedule.createCreate/update schedules
schedule.deleteDelete schedules
databasesView databases
databases.createCreate databases
databases.deleteDelete databases
startStart server
stopStop server
restartRestart server
killKill server
reinstallReinstall server
websocket.connectConnect to WebSocket