pterodactyl-js

A fully-typed, zero-dependency TypeScript SDK for the Pterodactyl Panel API.

Features

• Full coverage — Client API + Application API in one package
• 100% TypeScript — every request and response is typed
• Zero dependencies — uses the native fetch available in Node 18+
• Auto-pagination — listAll() fetches every page automatically
• Smart retries — rate limit errors are retried with backoff automatically
• Typed errors — NotFoundError, AuthenticationError, RateLimitError, and more

Installation

npm install pterodactyl-js

Requires Node.js >= 18

Quick Start

import { ClientAPI, ApplicationAPI } from 'pterodactyl-js'

// Client API — for your own servers
const client = new ClientAPI({
  url: 'https://panel.example.com',
  apiKey: 'ptlc_your_client_api_key',
})

// Application API — for panel administration
const app = new ApplicationAPI({
  url: 'https://panel.example.com',
  apiKey: 'ptla_your_application_api_key',
})

Client API

Servers

// List all servers (single page)
const page = await client.servers.list({ page: 1, perPage: 50 })

// List ALL servers across every page automatically
const all = await client.servers.listAll()

// Get a single server
const server = await client.servers.get('abc123')

// Get live resource usage
const resources = await client.servers.resources('abc123')
console.log(resources.current_state)           // 'running' | 'offline' | ...
console.log(resources.resources.cpu_absolute)  // CPU %
console.log(resources.resources.memory_bytes)  // RAM in bytes

// Power actions
await client.servers.power('abc123', 'start')
await client.servers.power('abc123', 'stop')
await client.servers.power('abc123', 'restart')
await client.servers.power('abc123', 'kill')

// Send a console command
await client.servers.command('abc123', 'say Hello!')

// Rename / reinstall
await client.servers.rename('abc123', 'New Name')
await client.servers.reinstall('abc123')

Files

// List files
const files = await client.files.list('abc123', '/home/container')

// Read file content
const content = await client.files.read('abc123', '/home/container/config.json')

// Write a file
await client.files.write('abc123', '/home/container/config.json', '{"debug":true}')

// Rename / move
await client.files.rename('abc123', '/home/container', [
  { from: 'old-name.txt', to: 'new-name.txt' }
])

// Copy
await client.files.copy('abc123', '/home/container/config.json')

// Delete
await client.files.delete('abc123', '/home/container', ['file1.txt', 'file2.txt'])

// Create directory
await client.files.createDirectory('abc123', '/home/container', 'my-folder')

// Compress / decompress
const archive = await client.files.compress('abc123', '/home/container', ['a.txt', 'b.txt'])
await client.files.decompress('abc123', '/home/container', 'archive.tar.gz')

// Get download / upload URLs
const downloadUrl = await client.files.download('abc123', '/home/container/server.jar')
const uploadUrl = await client.files.uploadUrl('abc123')

Backups

// List backups
const backups = await client.backups.list('abc123')

// Create a backup
const backup = await client.backups.create('abc123', {
  name: 'Before update',
  is_locked: true,
})

// Get a download URL
const url = await client.backups.download('abc123', backup.uuid)

// Restore from backup
await client.backups.restore('abc123', backup.uuid)

// Toggle lock
await client.backups.toggleLock('abc123', backup.uuid)

// Delete
await client.backups.delete('abc123', backup.uuid)

Databases

const dbs = await client.databases.list('abc123')

const db = await client.databases.create('abc123', {
  database: 's1_mydb',
  remote: '%',
})

await client.databases.rotatePassword('abc123', db.id)
await client.databases.delete('abc123', db.id)

Schedules & Tasks

// Create a schedule
const schedule = await client.schedules.create('abc123', {
  name: 'Daily restart',
  minute: '0',
  hour: '4',
  day_of_month: '*',
  day_of_week: '*',
  is_active: true,
})

// Add a task to the schedule
await client.schedules.createTask('abc123', schedule.id, {
  action: 'power',
  payload: 'restart',
  time_offset: 0,
})

// Add a command task
await client.schedules.createTask('abc123', schedule.id, {
  action: 'command',
  payload: 'say Server restarting in 1 minute!',
  time_offset: -60,
})

Network / Allocations

const allocations = await client.network.list('abc123')
await client.network.setPrimary('abc123', allocations[0]!.id)
await client.network.setNote('abc123', allocations[0]!.id, { notes: 'Main port' })

Sub-Users

const subuser = await client.subusers.create('abc123', {
  email: '[email protected]',
  permissions: [
    'control.console',
    'control.start',
    'control.stop',
    'control.restart',
  ],
})

await client.subusers.update('abc123', subuser.uuid, {
  permissions: ['control.console'],
})

await client.subusers.delete('abc123', subuser.uuid)

Startup Variables

const vars = await client.startup.list('abc123')
await client.startup.update('abc123', 'SERVER_JARFILE', 'paper.jar')

Application API

Servers

// List all servers
const servers = await app.servers.listAll()

// Filter by name
const filtered = await app.servers.listAll({
  filter: { name: 'my-server' },
})

// Get by ID or external ID
const server = await app.servers.get(42)
const byExtId = await app.servers.getByExternalId('ext-abc')

// Create a server
const newServer = await app.servers.create({
  name: 'Minecraft SMP',
  user: 1,
  egg: 3,
  docker_image: 'ghcr.io/pterodactyl/yolks:java_17',
  startup: 'java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar server.jar',
  environment: { MINECRAFT_VERSION: '1.21', SERVER_JARFILE: 'server.jar', BUILD_NUMBER: 'latest' },
  limits: { memory: 2048, swap: 0, disk: 10240, io: 500, cpu: 200, threads: null },
  feature_limits: { databases: 1, allocations: 1, backups: 3 },
  allocation: { default: 1 },
})

// Update details / build / startup
await app.servers.updateDetails(42, { name: 'New Name' })
await app.servers.updateBuild(42, { limits: { memory: 4096 } })
await app.servers.updateStartup(42, { environment: { SERVER_JARFILE: 'paper.jar' } })

// Lifecycle
await app.servers.suspend(42)
await app.servers.unsuspend(42)
await app.servers.reinstall(42)
await app.servers.delete(42)
await app.servers.delete(42, true) // force delete

Users

const users = await app.users.listAll()
const user = await app.users.get(1)

const newUser = await app.users.create({
  email: '[email protected]',
  username: 'newuser',
  first_name: 'Ahmed',
  last_name: 'Hassan',
})

await app.users.update(newUser.id, { root_admin: true })
await app.users.delete(newUser.id)

Nodes

const nodes = await app.nodes.listAll()
const config = await app.nodes.getConfiguration(1)

const node = await app.nodes.create({
  name: 'Egypt Node 1',
  location_id: 1,
  fqdn: 'node1.example.com',
  scheme: 'https',
  memory: 32768,
  disk: 500000,
})

// Manage allocations
await app.nodes.allocations.create(node.id, '0.0.0.0', ['25565', '25566'])
const allocs = await app.nodes.allocations.listAll(node.id)
await app.nodes.allocations.delete(node.id, allocs[0]!.id)

Locations

const locations = await app.locations.listAll()

const loc = await app.locations.create({ short: 'EG', long: 'Egypt' })
await app.locations.update(loc.id, { long: 'Egypt — Cairo' })
await app.locations.delete(loc.id)

Nests & Eggs

const nests = await app.nests.listAll()

for (const nest of nests) {
  const eggs = await app.nests.eggs.listAll(nest.id)
  console.log(`${nest.name}:`, eggs.map((e) => `${e.id} — ${e.name}`))
}

Error Handling

import {
  NotFoundError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  ServerError,
  PterodactylError,
} from 'pterodactyl-js'

try {
  await client.servers.get('doesnt-exist')
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Server not found')
  } else if (err instanceof AuthenticationError) {
    console.log('Bad API key or no permission')
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${err.retryAfter}s`)
  } else if (err instanceof ValidationError) {
    console.log('Validation errors:', err.errors)
  } else if (err instanceof ServerError) {
    console.log(`Panel error: ${err.status}`)
  } else if (err instanceof PterodactylError) {
    console.log(`API error: ${err.message}`)
  }
}

Configuration

const client = new ClientAPI({
  url: 'https://panel.example.com', // required — no trailing slash needed
  apiKey: 'ptlc_...',               // required
  timeout: 15000,                   // optional — ms (default: 10000)
  retries: 5,                       // optional — rate limit retries (default: 3)
})

License

MIT © funx8