Servers - StellarStack

List Servers

GET /api/servers
Authorization: Bearer {token}

Lists all servers. Users see their own servers, admins see all servers.

Authentication

Requires authentication with valid session token.

Response

servers

array

Array of server objects

Show Server Object

string

Server UUID

shortId

string

First section of UUID

name

string

Server name

description

string

Server description

status

string

memory

string

Memory limit in MiB (BigInt as string)

disk

string

Disk limit in MiB (BigInt as string)

cpu

number

CPU limit as percentage (100 = 1 core)

swap

string

Swap in MiB: -1 = unlimited, 0 = disabled, positive values = limited

node

object

Node information

blueprint

object

Blueprint information

owner

object

Owner information

allocations

array

Network allocations

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "shortId": "550e8400",
    "name": "Minecraft Server",
    "description": "My awesome server",
    "status": "RUNNING",
    "memory": "2048",
    "disk": "10240",
    "cpu": 100,
    "swap": "-1",
    "node": {
      "id": "node-1",
      "displayName": "US East 1",
      "isOnline": true,
      "location": {
        "name": "New York",
        "country": "US"
      }
    },
    "blueprint": {
      "id": "minecraft",
      "name": "Minecraft Java"
    },
    "allocations": [
      {
        "id": "alloc-1",
        "ip": "0.0.0.0",
        "port": 25565,
        "alias": "Main"
      }
    ]
  }
]

Get Server

GET /api/servers/{serverId}
Authorization: Bearer {token}

Retrieve detailed information about a specific server.

Path Parameters

serverId

string

required

Server UUID

Authentication

Requires server access (owner, admin, or member with permissions).

Response

Returns a detailed server object with all fields.

Create Server

POST /api/servers
Authorization: Bearer {token}
Content-Type: application/json

Create a new server instance. Admin only.

Authentication

Requires admin role.

Request Body

name

string

required

Server name (1-100 characters)

description

string

Server description

nodeId

string

required

Node UUID where server will be deployed

blueprintId

string

required

Blueprint UUID (game type)

ownerId

string

Owner user ID (defaults to current user)

memory

number

required

Memory limit in MiB

disk

number

required

Disk limit in MiB

cpu

number

required

CPU as percentage (100 = 1 thread)

cpuPinning

string

CPU pinning (e.g., “0,1,2,3” or “0-4”)

swap

number

default:"-1"

Swap in MiB: -1 = unlimited, 0 = disabled, positive values = limited

oomKillDisable

boolean

default:"false"

Disable OOM killer

backupLimit

number

default:"3"

Maximum number of backups

allocationLimit

number

default:"1"

Maximum allocations user can add

allocationIds

array

required

Array of allocation IDs (at least one required)

config

object

Override blueprint config

variables

object

Override blueprint variables (key-value pairs)

dockerImage

string

Selected docker image from blueprint

autoShutdownEnabled

boolean

null = inherit global, true = enabled, false = disabled

autoShutdownTimeout

number

Inactivity timeout in minutes (1-10080)

{
  "name": "My Minecraft Server",
  "description": "Survival server",
  "nodeId": "node-uuid",
  "blueprintId": "minecraft-java",
  "memory": 2048,
  "disk": 10240,
  "cpu": 100,
  "swap": 512,
  "backupLimit": 5,
  "allocationLimit": 2,
  "allocationIds": ["alloc-1"],
  "variables": {
    "MINECRAFT_VERSION": "1.20.4",
    "SERVER_JARFILE": "server.jar"
  },
  "dockerImage": "ghcr.io/pterodactyl/yolks:java_21"
}

Response

Returns the created server object with status 201.

Errors

400 - Validation failed, node offline, insufficient resources, or invalid allocations
404 - Node or blueprint not found
500 - Daemon communication error

Update Server

PATCH /api/servers/{serverId}
Authorization: Bearer {token}
Content-Type: application/json

Update server configuration.

Path Parameters

serverId

string

required

Server UUID

Request Body

All fields are optional. Only admins can modify resources and status.

name

string

Server name (1-100 characters)

description

string

Server description

memory

number

Memory limit in MiB (admin only)

disk

number

Disk limit in MiB (admin only)

cpu

number

CPU percentage (admin only)

status

string

Server status (admin only)

autoShutdownEnabled

boolean

Auto-shutdown setting (admin only)

Response

Returns the updated server object.

Delete Server

DELETE /api/servers/{serverId}
Authorization: Bearer {token}

Permanently delete a server. Admin only.

Path Parameters

serverId

string

required

Server UUID

Response

{ "success": true }

Power Actions

Start Server

POST /api/servers/{serverId}/start
Authorization: Bearer {token}

Start the server.

Stop Server

POST /api/servers/{serverId}/stop
Authorization: Bearer {token}

Gracefully stop the server using configured stop command.

Restart Server

POST /api/servers/{serverId}/restart
Authorization: Bearer {token}

Restart the server.

Kill Server

POST /api/servers/{serverId}/kill
Authorization: Bearer {token}

Forcefully kill the server process (SIGKILL).

Response

All power actions return:

{
  "success": true,
  "status": "STARTING" // or STOPPING, STOPPED
}

Errors

400 - Node is offline or server is suspended
500 - Daemon communication error

Send Command

POST /api/servers/{serverId}/command
Authorization: Bearer {token}
Content-Type: application/json

Send a command to the server console.

Request Body

command

string

required

Command to execute

{
  "command": "say Hello world!"
}

Response

{ "success": true }

Get Console Connection

GET /api/servers/{serverId}/console
Authorization: Bearer {token}

Get WebSocket connection information for server console.

Response

websocketUrl

string

WebSocket URL to connect to

token

string

JWT token for WebSocket authentication (expires in 15 minutes)

{
  "websocketUrl": "wss://node.example.com:8080/api/servers/550e8400-e29b-41d4-a716-446655440000/ws",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Startup Configuration

Get Startup Config

GET /api/servers/{serverId}/startup
Authorization: Bearer {token}

Get server startup configuration including variables and docker images.

Response

variables

array

Environment variables

dockerImages

array

Available docker images

selectedDockerImage

string

Currently selected docker image

startupCommand

string

Generated startup command with variables substituted

stopCommand

string

Stop command (e.g., “stop” or “SIGTERM”)

Update Startup Config

PATCH /api/servers/{serverId}/startup
Authorization: Bearer {token}
Content-Type: application/json

Request Body

variables

object

Updated variable values (key-value pairs)

dockerImage

string

Selected docker image from available options

customStartupCommands

string

Custom commands to append

Reinstall Server

POST /api/servers/{serverId}/reinstall
Authorization: Bearer {token}

Run the installation script again (wipes server files).

Response

{
  "success": true,
  "message": "Server reinstalling...",
  "status": "INSTALLING"
}

Change Blueprint

POST /api/servers/{serverId}/change-blueprint
Authorization: Bearer {token}
Content-Type: application/json

Change the server’s blueprint (game type).

Request Body

blueprintId

string

required

New blueprint UUID

dockerImage

string

Docker image from new blueprint

variables

object

Variable overrides for new blueprint

reinstall

boolean

default:"false"

Whether to trigger reinstallation

Response

{
  "success": true,
  "message": "Blueprint changed successfully",
  "server": { /* server object */ },
  "reinstalling": false
}

File Management

File management endpoints are integrated with the server management API. See the File Manager documentation for details on file operations.

Backups

See Backups for backup management endpoints.

Introduction

Endpoints

​List Servers

​Authentication

​Response

​Get Server

​Path Parameters

​Authentication

​Response

​Create Server

​Authentication

​Request Body

​Response

​Errors

​Update Server

​Path Parameters

​Request Body

​Response

​Delete Server

​Path Parameters

​Response

​Power Actions

​Start Server

​Stop Server

​Restart Server

​Kill Server

​Response

​Errors

​Send Command

​Request Body

​Response

​Get Console Connection

​Response

​Startup Configuration

​Get Startup Config

​Response

​Update Startup Config

​Request Body

​Reinstall Server

​Response

​Change Blueprint

​Request Body

​Response

​File Management

​Backups

Build docs developers (and LLMs) love

List Servers

Authentication

Response

Get Server

Path Parameters

Authentication

Response

Create Server

Authentication

Request Body

Response

Errors

Update Server

Path Parameters

Request Body

Response

Delete Server

Path Parameters

Response

Power Actions

Start Server

Stop Server

Restart Server

Kill Server

Response

Errors

Send Command

Request Body

Response

Get Console Connection

Response

Startup Configuration

Get Startup Config

Response

Update Startup Config

Request Body

Reinstall Server

Response

Change Blueprint

Request Body

Response

File Management

Backups