Server Management

Overview

The Server API provides endpoints for managing Modrinth Hosting servers, including creation, configuration, power management, and console access. All endpoints require authentication via JWT token.

Authentication

All server API requests must include an Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Endpoints

Get Server

Retrieve detailed information about a specific server.

const server = await client.archon.servers_v0.get(serverId)

serverId

string

required

The unique identifier of the server

server_id

string

Unique server identifier

name

string

Server display name

owner_id

string

User ID of the server owner

net

object

Network configuration

string

Server IP address

port

number

Server port number

domain

string

Server domain name

game

string

Game type (e.g., “Minecraft”)

status

string

Server status: installing, broken, available, or suspended

suspension_reason

string | null

Reason for suspension: moderated, paymentfailed, cancelled, upgrading, or other

loader

string | null

Mod loader: Forge, NeoForge, Fabric, Quilt, Purpur, Spigot, Vanilla, or Paper

loader_version

string | null

Version of the mod loader

mc_version

string | null

Minecraft version

upstream

object | null

Upstream modpack configuration

kind

string

modpack or none

version_id

string

Modrinth version ID

project_id

string

Modrinth project ID

sftp_username

string

SFTP username for file access

sftp_password

string

SFTP password for file access

sftp_host

string

SFTP host address

datacenter

string

Datacenter location

backup_quota

number

Maximum number of backups allowed

used_backup_quota

number

Number of backups currently in use

is_medal

boolean

Whether the server is a Medal (sponsored) server

medal_expires

string

ISO 8601 timestamp when Medal status expires

List Servers

Retrieve a paginated list of servers for the authenticated user.

const { servers, pagination } = await client.archon.servers_v0.list({
  limit: 20,
  offset: 0
})

limit

number

Number of servers to return per page (default: 20)

offset

number

Number of servers to skip (default: 0)

servers

array

Array of server objects (see Get Server response)

pagination

object

Pagination metadata

current_page

number

Current page number

page_size

number

Number of items per page

total_pages

number

Total number of pages

total_items

number

Total number of servers

Check Stock Availability

Check if a server configuration is available in a specific region.

const stock = await client.archon.servers_v0.checkStock('us-east', {
  cpu: 2,
  memory_mb: 4096,
  swap_mb: 1024,
  storage_mb: 10240
})

region

string

required

Region shortcode (e.g., “us-east”, “eu-west”)

cpu

number

Number of CPU cores

memory_mb

number

Memory in megabytes

swap_mb

number

Swap space in megabytes

storage_mb

number

Storage space in megabytes

available

number

Number of available server slots with this configuration

Get Available Regions

Retrieve a list of all available hosting regions.

const regions = await client.archon.servers_v1.getRegions()

shortcode

string

Region identifier (e.g., “us-east”)

country_code

string

ISO country code

display_name

string

Human-readable region name

lat

number

Latitude coordinate

lon

number

Longitude coordinate

zone

string

Availability zone

Power Management

Send Power Action

Control server power state.

// Start the server
await client.archon.servers_v0.power(serverId, 'Start')

// Stop the server gracefully
await client.archon.servers_v0.power(serverId, 'Stop')

// Restart the server
await client.archon.servers_v0.power(serverId, 'Restart')

// Force kill the server
await client.archon.servers_v0.power(serverId, 'Kill')

serverId

string

required

The unique identifier of the server

action

string

required

Power action: Start, Stop, Restart, or Kill

Power state changes are broadcast via WebSocket events (see WebSocket API).

Console Access

Server console access is provided via WebSocket connections. See the WebSocket API documentation for details on:

Receiving real-time log output
Sending console commands
Monitoring server statistics

File Management

Get Filesystem Authentication

Obtain credentials for accessing a server’s filesystem via the Kyros API.

const { url, token } = await client.archon.servers_v0.getFilesystemAuth(serverId)

// Use the token with Kyros file operations
const files = await client.kyros.files_v0.listDirectory('/', 1, 100)

serverId

string

required

The unique identifier of the server

url

string

Base URL for Kyros filesystem API (e.g., “node-xyz.modrinth.com/modrinth/v0/fs”)

token

string

JWT token for authenticating filesystem requests

The token is automatically used by the Kyros file API when you call methods like:

listDirectory() - Browse files and folders
uploadFile() - Upload files with progress tracking
downloadFile() - Download files
createFileOrFolder() - Create new files/directories
deleteFileOrFolder() - Delete files/directories
moveFileOrFolder() - Move or rename files
updateFile() - Update file contents

See the Kyros Files API documentation for complete file management capabilities.

Installing Mods

List Installed Mods

Get a list of all mods installed on a server.

const mods = await client.archon.content_v0.list(serverId)

serverId

string

required

The unique identifier of the server

filename

string

Mod file name

project_id

string | undefined

Modrinth project ID

version_id

string | undefined

Modrinth version ID

name

string | undefined

Mod display name

version_number

string | undefined

Mod version number

icon_url

string | undefined

URL to mod icon image

owner

string | undefined

Mod author/owner

disabled

boolean

Whether the mod is disabled

installing

boolean

Whether the mod is currently being installed

Install a Mod

Install a mod or plugin from Modrinth.

await client.archon.content_v0.install(serverId, {
  rinth_ids: {
    project_id: 'P7dR8mSH',
    version_id: 'abc123'
  },
  install_as: 'mod'
})

// Listen for installation result via WebSocket
const unsub = client.archon.sockets.on(serverId, 'installation-result', (event) => {
  if (event.result === 'ok') {
    console.log('Mod installed successfully')
  } else {
    console.error('Installation failed:', event.reason)
  }
})

serverId

string

required

The unique identifier of the server

rinth_ids.project_id

string

required

Modrinth project ID

rinth_ids.version_id

string

required

Modrinth version ID

install_as

string

required

Content type: mod or plugin

Installation progress is broadcast via WebSocket installation-result events.

Update a Mod

Update an existing mod to a new version.

await client.archon.content_v0.update(serverId, {
  replace: '/mods/sodium-0.5.0.jar',
  project_id: 'AANobbMI',
  version_id: 'new-version-id'
})

serverId

string

required

The unique identifier of the server

replace

string

required

Path to the existing mod file to replace

project_id

string

required

Modrinth project ID

version_id

string

required

New Modrinth version ID

Delete a Mod

Remove a mod from the server.

await client.archon.content_v0.delete(serverId, {
  path: '/mods/example-mod.jar'
})

serverId

string

required

The unique identifier of the server

path

string

required

Path to the mod file to delete

Example: Complete Server Setup

import { GenericModrinthClient } from '@modrinth/api-client'

// Initialize client
const client = new GenericModrinthClient({
  token: 'your-auth-token'
})

// Get server details
const server = await client.archon.servers_v0.get('server-id')
console.log(`Server: ${server.name} (${server.status})`)

// Start the server
await client.archon.servers_v0.power(server.server_id, 'Start')

// Connect to WebSocket for real-time updates
await client.archon.sockets.safeConnect(server.server_id)

// Listen for power state changes
const unsubPower = client.archon.sockets.on(server.server_id, 'power-state', (event) => {
  console.log(`Power state: ${event.state}`)
})

// Listen for console logs
const unsubLogs = client.archon.sockets.on(server.server_id, 'log', (event) => {
  console.log(`[${event.stream}] ${event.message}`)
})

// Send a console command
client.archon.sockets.send(server.server_id, {
  event: 'command',
  cmd: '/say Hello from API!'
})

// Install a mod
await client.archon.content_v0.install(server.server_id, {
  rinth_ids: {
    project_id: 'P7dR8mSH',
    version_id: 'abc123'
  },
  install_as: 'mod'
})

// Clean up
unsubPower()
unsubLogs()
client.archon.sockets.disconnect(server.server_id)

WebSocket API - Real-time server events and console access
Backups API - Server backup management

Getting Started

Core Resources

Content & Search

Server Hosting API

Client Libraries

Server Management

Overview

Authentication

Endpoints

Get Server

List Servers

Check Stock Availability

Get Available Regions

Power Management

Send Power Action

Console Access

File Management

Get Filesystem Authentication

Installing Mods

List Installed Mods

Install a Mod

Update a Mod

Delete a Mod

Example: Complete Server Setup

Getting Started

Core Resources

Content & Search

Server Hosting API

Client Libraries

​Overview

​Authentication

​Endpoints

​Get Server

​List Servers

​Check Stock Availability

​Get Available Regions

​Power Management

​Send Power Action

​Console Access

​File Management

​Get Filesystem Authentication

​Installing Mods

​List Installed Mods

​Install a Mod

​Update a Mod

​Delete a Mod

​Example: Complete Server Setup

​Related Documentation

Overview

Authentication

Endpoints

Get Server

List Servers

Check Stock Availability

Get Available Regions

Power Management

Send Power Action

Console Access

File Management

Get Filesystem Authentication

Installing Mods

List Installed Mods

Install a Mod

Update a Mod

Delete a Mod

Example: Complete Server Setup

Related Documentation