API Docs

Upserts server state by serverId. Latest heartbeat fully replaces the previous server snapshot.

• Heartbeat window: 15 seconds
• Only human slots count as players
• Rate-limited per serverId

curl -X POST http://localhost:3000/v1/heartbeat \
  -H "Content-Type: application/json" \
  -d '{
    "serverId": "us-east-1-03",
    "sessionId": "qm-2026-02-17-a1",
    "matchId": "m-0042",
    "region": "us-east-1",
    "hostPort": 47777,
    "currentTrackScene": "Track - Pittsboro SX",
    "maxPlayers": 30,
    "slots": [],
    "serverTimeMs": 1771286400000
  }'

Return type (TypeScript)

type ServerHeartbeatResponse = {
  ok: true;
  receivedAtMs: number;
  activeUntilMs: number;
};

Example response

{
  "ok": true,
  "receivedAtMs": 1771286400450,
  "activeUntilMs": 1771286415450
}

Test route

Returns only active servers, sorted by region then serverId.

curl http://localhost:3000/v1/list-servers

Return type (TypeScript)

type HumanPlayer = {
  slotIndex: number;
  ownerClientId: number;
  riderName: string;
  riderNumber: number;
};

type ActiveServer = {
  serverId: string;
  sessionId: string;
  matchId: string;
  region: string;
  hostIpAddress: string;
  hostPort: number;
  currentTrackScene: string;
  playerCount: number;
  maxPlayers: number;
  players: HumanPlayer[];
  lastHeartbeatAtMs: number;
  activeUntilMs: number;
};

type AdminServersResponse = {
  generatedAtMs: number;
  activeWindowSec: number;
  servers: ActiveServer[];
};

Example response

{
  "generatedAtMs": 1771286402000,
  "activeWindowSec": 15,
  "servers": [
    {
      "serverId": "us-east-1-03",
      "sessionId": "qm-2026-02-17-a1",
      "matchId": "m-0042",
      "region": "us-east-1",
      "hostIpAddress": "203.0.113.10",
      "hostPort": 47777,
      "currentTrackScene": "Track - Pittsboro SX",
      "playerCount": 2,
      "maxPlayers": 30,
      "players": [
        {
          "slotIndex": 0,
          "ownerClientId": 0,
          "riderName": "Jim",
          "riderNumber": 27
        },
        {
          "slotIndex": 4,
          "ownerClientId": 12,
          "riderName": "Ava",
          "riderNumber": 14
        }
      ],
      "lastHeartbeatAtMs": 1771286400450,
      "activeUntilMs": 1771286415450
    }
  ]
}

Test route

Returns one active server with available capacity and prefers a matching region when provided.

curl "http://localhost:3000/v1/matchmake?region=us-east-1"

Return type (TypeScript)

type MatchmakeResponse = {
  generatedAtMs: number;
  server: ActiveServer | null;
};

Example response

{
  "generatedAtMs": 1771286402500,
  "server": {
    "serverId": "us-east-1-03",
    "sessionId": "qm-2026-02-17-a1",
    "matchId": "m-0042",
    "region": "us-east-1",
    "hostIpAddress": "203.0.113.10",
    "hostPort": 47777,
    "currentTrackScene": "Track - Pittsboro SX",
    "playerCount": 2,
    "maxPlayers": 30,
    "players": [
      { "slotIndex": 0, "ownerClientId": 0, "riderName": "Jim", "riderNumber": 27 }
    ],
    "lastHeartbeatAtMs": 1771286400450,
    "activeUntilMs": 1771286415450
  }
}

Test route