Game Servers API

Overview

The Game Servers API lets you list, get, create, update, and delete game servers. All endpoints are organization-scoped.

Base route

list()

List game servers with optional pagination and filters.

HTTP API

Query parameters

Headers: Authorization: Bearer <your-api-key>

Example (cURL)

curl -X GET "https://api.sweathost.com/v1/game-servers?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

Parameters

Return type: Promise<ListGameServersResponse<GameServer['configuration']>>

Example

const response = await client.gameServers.list();
console.log(`Found ${response.total} servers`);

const page2 = await client.gameServers.list({ page: 2, pageSize: 50 });

Response structure

ListGameServersResponse: { page, pageSize, total, items }. Each item is GameServer:

get()

Get a single game server by ID.

HTTP API

Path parameters

Headers: Authorization: Bearer <your-api-key>

Example (cURL)

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

SDK

Parameters

Return type: Promise<GameServer>

Example

const server = await client.gameServers.get('server_abc123');
console.log(`${server.name}: ${server.ip}:${server.port}`);
console.log(`Status: ${server.status}`);

getStatus()

Get lightweight server status for polling. Use this when you have pending servers and want to check allocation progress without fetching the full server object.

HTTP API

Path parameters

Response: { id, status, ip?, port?, lastError?, queuedAt?, updatedAt }

SDK

Parameters

Return type: Promise<ServerStatusResponse>

Example

const status = await client.gameServers.getStatus('server_abc123');
if (status.status === 'running') {
  console.log(`Ready: ${status.ip}:${status.port}`);
} else if (status.status === 'failed') {
  console.error(`Failed: ${status.lastError}`);
}

waitForServer()

Poll until a server reaches running or failed. Useful when create() returns pending and you want to block until the server is ready.

SDK only (no direct HTTP equivalent)

Parameters

Return type: Promise<GameServer>

Throws: Error if server reaches failed status.

Example

const server = await client.gameServers.create({ /* ... */ });
if (server.status === 'pending') {
  const ready = await client.gameServers.waitForServer(server.id, 5000);
  console.log(`Server ready: ${ready.ip}:${ready.port}`);
}

create()

Create a new game server. The API tries immediate allocation; if no capacity is available, the server is queued for background provisioning and returns with status: 'pending'.

Provisioning flow

1. Immediate success: If capacity is available, the server is allocated and returns with status: 'running'.
2. Queued: If no capacity, the server is created with status: 'pending' and processed by a background job (every 30 seconds). You'll receive the server object immediately; poll get() or getStatus() for updates.
3. Failed: After 3 allocation attempts, the server is marked status: 'failed' with lastAllocationError set.

HTTP API

Headers: Authorization: Bearer <your-api-key>, Content-Type: application/json

Request body

Example (cURL)

curl -X POST "https://api.sweathost.com/v1/game-servers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My CS2 Server","gameType":"cs2","region":"us-east-1","configuration":{...}}'

SDK

Parameters

Return type: Promise<GameServer>

Example (async mode – default)

const server = await client.gameServers.create({
  name: 'My CS2 Server',
  gameType: 'cs2',
  region: 'us-east-1',
  configuration: {
    gameMode: 'competitive',
    maxPlayers: 10,
    tickrate: 128,
    rconPassword: 'secure-rcon',
    enableVAC: true,
    mapPool: ['de_dust2', 'de_mirage'],
    startingMap: 'de_dust2',
    enableBots: false,
    tournamentMode: true,
    warmupTime: 60,
    freezeTime: 15,
    roundTime: 115,
    bombTimer: 40,
    buyTime: 20,
  },
});

if (server.status === 'pending' || server.status === 'allocating') {
  const ready = await client.gameServers.waitForServer(server.id, 5000);
  console.log(`Ready: ${ready.ip}:${ready.port}`);
} else {
  console.log(`Created: ${server.id} at ${server.ip}:${server.port}`);
}

Example (blocking mode)

const server = await client.gameServers.create(
  { name: 'My Server', gameType: 'cs2', region: 'us-east-1', configuration: { /* ... */ } },
  { wait: true, pollInterval: 5000 }
);
console.log(`Ready: ${server.ip}:${server.port}`);

CS2 configuration (Cs2ServerConfiguration): gameMode, maxPlayers, tickrate, serverPassword?, rconPassword, enableVAC, mapPool, startingMap, enableBots, botDifficulty, tournamentMode, warmupTime, freezeTime, roundTime, bombTimer, buyTime, customCvars?.

update()

Update an existing game server.

HTTP API

Path parameters

Request body: Partial { name?, configuration?, autoStop?, autostopMinutes? }.

Headers: Authorization: Bearer <your-api-key>, Content-Type: application/json

Example (cURL)

curl -X PATCH "https://api.sweathost.com/v1/game-servers/SERVER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Name","configuration":{...}}'

SDK

Parameters

Return type: Promise<GameServer>

Example

const server = await client.gameServers.update('server_abc123', {
  name: 'Updated Server Name',
  configuration: { maxPlayers: 12 },
});

delete()

Delete (soft-delete) a game server.

HTTP API

Path parameters

Headers: Authorization: Bearer <your-api-key>

Example (cURL)

curl -X DELETE "https://api.sweathost.com/v1/game-servers/SERVER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK

Parameters

Return type: Promise<{ ok: true }>

Example

await client.gameServers.delete('server_abc123');

events (HTTP only)

Poll for server provisioning events (e.g. when a queued server becomes ready). Used by the dashboard for in-app notifications.

Query parameters

Response: { events: [{ id, serverId, eventType, eventData, createdAt }] }

Event types: provisioning_completed, provisioning_failed

Errors

Note: When no capacity is available, create() returns 200 with status: 'pending' instead of 503. The server is queued for background allocation.

Ensure your API key has the appropriate scopes for game server management.