Client API: client server management endpoints

The server endpoints under /api/client/servers give you access to every server your account can see. All endpoints require authentication. Subusers can access server endpoints for servers they have been granted access to, subject to their configured permissions.

The {server} path parameter accepts the server UUID or the short numeric ID.

List servers

Returns a paginated list of servers owned by the authenticated user.

GET /api/client/servers

page

integer

default:"1"

Page number.

per_page

integer

default:"10"

Items per page (1–100).

string

Filter by server name.

other

boolean

default:"false"

When true and caller has admin servers.read, returns servers not owned by the caller.

Required permission: servers.read

curl
Response

curl https://your-panel.example.com/api/client/servers \
  -H "Authorization: Bearer ptlc_YourKey"

{
  "servers": {
    "data": [
      {
        "uuid": "abc12345-...",
        "name": "Minecraft SMP",
        "status": null,
        "suspended": false
      }
    ],
    "total": 1,
    "per_page": 10,
    "page": 1
  }
}

Get a server

Returns a single server object.

GET /api/client/servers/{server}

server

string

required

Server UUID or short ID.

Required permission: servers.view

Send a power action

Starts, stops, restarts, or kills a server.

POST /api/client/servers/{server}/power

server

string

required

Server UUID or short ID.

action

string

required

One of start, stop, restart, or kill. Also accepted as signal for compatibility.

Required permission: control.start / control.stop / control.restart (matched to the action)

curl
Response

curl -X POST https://your-panel.example.com/api/client/servers/{server}/power \
  -H "Authorization: Bearer ptlc_YourKey" \
  -H "Content-Type: application/json" \
  -d '{"action": "start"}'

{}

Send a console command

Sends a command to the server console.

POST /api/client/servers/{server}/command

server

string

required

Server UUID or short ID.

command

string

required

The command string to send. Maximum 1024 characters.

Required permission: control.console

Get resource usage

Returns current CPU, memory, disk, and network usage for the server.

GET /api/client/servers/{server}/resources

server

string

required

Server UUID or short ID.

resources

object

Current resource usage returned from the Wings node.

Show properties

cpu_absolute

number

CPU usage as a percentage (absolute, not relative to limit).

memory_bytes

integer

Current memory usage in bytes.

disk_bytes

integer

Current disk usage in bytes.

network

object

Network I/O counters (rx/tx bytes).

state

string

Server process state: running, offline, starting, stopping.

Get WebSocket token

Returns a short-lived JWT and WebSocket URL for connecting to the server’s real-time console. Tokens expire after 10 minutes.

GET /api/client/servers/{server}/websocket

server

string

required

Server UUID or short ID.

token

string

Signed JWT to use as authentication when connecting to the WebSocket.

url

string

WebSocket URL (ws:// or wss://) to connect to.

Files

List files

GET /api/client/servers/{server}/files/list

server

string

required

Server UUID or short ID.

Read file contents

Returns the raw text content of a file.

GET /api/client/servers/{server}/files/contents

server

string

required

Server UUID or short ID.

file

string

required

Full path of the file to read.

Required permission: files.read-content

Write file contents

Writes the request body as the file’s new content.

POST /api/client/servers/{server}/files/write

server

string

required

Server UUID or short ID.

file

string

required

Full path of the file to write.

The request body should be the raw file content as plain text (Content-Type: text/plain). Required permission: files.create

Delete files

POST /api/client/servers/{server}/files/delete

server

string

required

Server UUID or short ID.

root

string

default:"/"

Root directory for the deletion operation.

files

string[]

required

List of file/directory names relative to root to delete.

Required permission: files.delete

Other file operations

Method	Path	Description	Permission
`GET`	`/files/download`	Get a signed download URL for a file.	`files.read`
`POST`	`/files/upload`	Upload a file.	`files.create`
`POST`	`/files/rename`	Rename files or directories.	`files.update`
`POST`	`/files/copy`	Copy a file.	`files.create`
`POST`	`/files/copy-many`	Copy multiple files.	`files.create`
`POST`	`/files/compress`	Compress files into an archive.	`files.archive`
`POST`	`/files/decompress`	Decompress an archive.	`files.archive`
`POST`	`/files/create-directory`	Create a new directory.	`files.create`
`POST`	`/files/chmod`	Change file permissions.	`files.update`
`GET`	`/files/search`	Search for files by name.	`files.read`

Backups

List backups

GET /api/client/servers/{server}/backups

server

string

required

Server UUID or short ID.

page

integer

default:"1"

Page number.

per_page

integer

default:"10"

Items per page.

string

Filter by backup name.

Required permission: backups.read

Create a backup

POST /api/client/servers/{server}/backups

server

string

required

Server UUID or short ID.

name

string

Display name for the backup. Maximum 255 characters. Defaults to a timestamp-based name.

ignored_files

string[]

List of file paths to exclude from the backup.

Required permission: backups.create Returns 417 Expectation Failed if the server’s backup limit has been reached.

Databases

List databases

GET /api/client/servers/{server}/databases

server

string

required

Server UUID or short ID.

include_password

boolean

default:"false"

Include the database password in the response. Requires databases.read-password.

page

integer

default:"1"

Page number.

per_page

integer

default:"10"

Items per page.

Required permission: databases.read

Create a database

POST /api/client/servers/{server}/databases

server

string

required

Server UUID or short ID.

database_host_uuid

string (UUID)

required

UUID of the database host to create the database on.

name

string

required

Database name. 3–31 alphanumeric/underscore characters.

Required permission: databases.create

Schedules

List schedules

GET /api/client/servers/{server}/schedules

server

string

required

Server UUID or short ID.

page

integer

default:"1"

Page number.

per_page

integer

default:"10"

Items per page.

Required permission: schedules.read

Create a schedule

POST /api/client/servers/{server}/schedules

server

string

required

Server UUID or short ID.

name

string

required

Schedule name. 1–255 characters.

enabled

boolean

required

Whether the schedule is active.

triggers

array

required

Array of trigger definitions (cron-based).

condition

object

required

Pre-condition that must be met before the schedule runs.

Required permission: schedules.create

Subusers

Subusers are other panel accounts that have been granted access to a server with a specific set of permissions.

List subusers

GET /api/client/servers/{server}/subusers

server

string

required

Server UUID or short ID.

page

integer

default:"1"

Page number.

per_page

integer

default:"10"

Items per page.

Required permission: subusers.read

Add a subuser

POST /api/client/servers/{server}/subusers

server

string

required

Server UUID or short ID.

string

required

Email address of the user to add.

permissions

string[]

required

List of server permission nodes to grant.

ignored_files

string[]

List of file paths to hide from this subuser.

Required permission: subusers.create

Subusers cannot be granted permissions that the server owner or calling user does not themselves hold.

Allocations

List allocations

GET /api/client/servers/{server}/allocations

Returns the IP/port allocations assigned to the server. Required permission: allocations.read

Startup

Get startup variables

GET /api/client/servers/{server}/startup

Returns the egg startup variables and their current values for this server. Required permission: startup.read

Update a startup variable

PUT /api/client/servers/{server}/startup/variables

Updates the value of a single egg variable. Required permission: startup.update

Settings

Method	Path	Description
`GET`	`/{server}/settings`	Get server settings (name, description, image).
`PATCH`	`/{server}/settings`	Update server name or description.

Overview

Client API

Admin API

Client API: client server management endpoints

List servers

Get a server

Send a power action

Send a console command

Get resource usage

Get WebSocket token

Files

List files

Read file contents

Write file contents

Delete files

Other file operations

Backups

List backups

Create a backup

Databases

List databases

Create a database

Schedules

List schedules

Create a schedule

Subusers

List subusers

Add a subuser

Allocations

List allocations

Startup

Get startup variables

Update a startup variable

Settings

Build docs developers (and LLMs) love

Overview

Client API

Admin API

Documentation Index

​List servers

​Get a server

​Send a power action

​Send a console command

​Get resource usage

​Get WebSocket token

​Files

​List files

​Read file contents

​Write file contents

​Delete files

​Other file operations

​Backups

​List backups

​Create a backup

​Databases

​List databases

​Create a database

​Schedules

​List schedules

​Create a schedule

​Subusers

​List subusers

​Add a subuser

​Allocations

​List allocations

​Startup

​Get startup variables

​Update a startup variable

​Settings

Build docs developers (and LLMs) love

List servers

Get a server

Send a power action

Send a console command

Get resource usage

Get WebSocket token

Files

List files

Read file contents

Write file contents

Delete files

Other file operations

Backups

List backups

Create a backup

Databases

List databases

Create a database

Schedules

List schedules

Create a schedule

Subusers

List subusers

Add a subuser

Allocations

List allocations

Startup

Get startup variables

Update a startup variable

Settings