API Examples

Common use cases for the RespawnHost API.

List Your Servers

curl -X GET "https://respawnhost.com/api/v1/servers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Server Details

Retrieve details for a specific server by UUID:

curl -X GET "https://respawnhost.com/api/v1/servers/{uuid}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Control Server Power State

Start, stop, restart, or kill a server:

curl -X POST "https://respawnhost.com/api/v1/servers/{uuid}/powerstate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal": "start"}'

Available signals: start, stop, restart, kill

Send Console Command

Execute a command on your running server:

curl -X POST "https://respawnhost.com/api/v1/servers/{uuid}/send-command" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Hello from the API!"}'

Create a Backup

curl -X POST "https://respawnhost.com/api/v1/servers/{uuid}/backups" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "pre-update-backup"}'

List Backups

curl -X GET "https://respawnhost.com/api/v1/servers/{uuid}/backups" \
  -H "Authorization: Bearer YOUR_API_KEY"

Restore a Backup

curl -X POST "https://respawnhost.com/api/v1/servers/{uuid}/backups/{backupId}/restore" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add ?truncate=true to delete existing files before restoring.

List Files

curl -X GET "https://respawnhost.com/api/v1/servers/{uuid}/files?directory=/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Read File Content

curl -X GET "https://respawnhost.com/api/v1/servers/{uuid}/files/content?file=/server.properties" \
  -H "Authorization: Bearer YOUR_API_KEY"

Write File Content

curl -X POST "https://respawnhost.com/api/v1/servers/{uuid}/files/write?file=/motd.txt" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  -d "Welcome to the server!"

Update Server Alias

curl -X PUT "https://respawnhost.com/api/v1/servers/{uuid}/alias" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alias": "My Minecraft Server"}'

Create a Database

curl -X POST "https://respawnhost.com/api/v1/servers/{uuid}/databases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mydb"}'

Get WebSocket Connection

For real-time console output, request WebSocket credentials:

curl -X GET "https://respawnhost.com/api/v1/servers/{uuid}/websocket" \
  -H "Authorization: Bearer YOUR_API_KEY"

This returns the WebSocket URL and authentication token for connecting to the live console.

TypeScript SDK Examples

Using the official @respawnhost/sdk, you can interact with the API using type-safe TypeScript:

Installation

npm install @respawnhost/sdk

Complete Server Management

import {
  RespawnHostClient,
  ServersService,
  PowerState,
  NotFoundError
} from '@respawnhost/sdk';

async function manageServer() {
  const client = new RespawnHostClient({
    apiKey: process.env.RESPAWNHOST_API_KEY!
  });
  
  const servers = new ServersService(client);
  
  try {
    // List all servers
    const { data: serverList } = await servers.list();
    
    if (serverList.length === 0) {
      console.log('No servers found');
      return;
    }
    
    const server = serverList[0];
    const uuid = server.panelUuid;
    
    // Check resource usage
    const resources = await servers.getResourceUtilization(uuid);
    console.log(`CPU: ${resources.cpu}%, Memory: ${resources.memory}MB`);
    
    // Create a backup
    const backup = await servers.backups.create(uuid, {
      name: `Backup - ${new Date().toISOString()}`
    });
    console.log(`Backup created: ${backup.backupName}`);
    
    // Send a command
    await servers.sendCommand(uuid, { 
      command: 'say Hello from the SDK!' 
    });
    
  } catch (error) {
    if (error instanceof NotFoundError) {
      console.error('Server not found');
    } else {
      throw error;
    }
  }
}

Automated Backup Script

import { RespawnHostClient, ServersService } from '@respawnhost/sdk';

async function backupAllServers() {
  const client = new RespawnHostClient({
    apiKey: process.env.RESPAWNHOST_API_KEY!
  });
  
  const servers = new ServersService(client);
  const { data: serverList } = await servers.list();
  
  for (const server of serverList) {
    try {
      const backup = await servers.backups.create(server.panelUuid, {
        name: `Auto backup - ${new Date().toLocaleDateString()}`
      });
      console.log(`✅ Backup created for ${server.alias}`);
    } catch (error) {
      console.error(`❌ Failed to backup ${server.alias}:`, error);
    }
  }
}

File Management

import { RespawnHostClient, ServersService } from '@respawnhost/sdk';

async function updateServerConfig(uuid: string) {
  const client = new RespawnHostClient({
    apiKey: process.env.RESPAWNHOST_API_KEY!
  });
  
  const servers = new ServersService(client);
  
  // Read current config
  const content = await servers.files.getContent(uuid, '/server.properties');
  
  // Update MOTD
  await servers.files.write(uuid, {
    file: '/server.properties',
    content: content.toString().replace(/motd=.*/, 'motd=Welcome!')
  });
  
  console.log('Config updated!');
}

Error Handling

import { 
  RespawnHostError,
  UnauthorizedError,
  ForbiddenError,
  NotFoundError,
  BadRequestError
} from '@respawnhost/sdk';

try {
  await servers.setPowerState('uuid', { power_state: PowerState.START });
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Server not found');
  } else if (error instanceof UnauthorizedError) {
    console.error('Invalid API key');
  } else if (error instanceof ForbiddenError) {
    console.error('Insufficient permissions');
  } else if (error instanceof RespawnHostError) {
    console.error(`API error (${error.statusCode}): ${error.message}`);
  }
}

For more SDK examples and full documentation, visit the npm package page.

More Endpoints

For the complete list of endpoints, request/response schemas, and the ability to test requests directly, visit the API Reference.