Server Management

API endpoints for managing Modrinth Hosting servers

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

ip · 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)

Related Documentation

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