API Reference

Matchmaking

Plugin-facing server/world matchmaking

POST /api/plugin/matchmaking/find

Find a server (or world) for a player

One endpoint, three modes chosen by which fields are set: serverType only picks the best server of a type; serverType + worldType picks the best world; serverId (and optional worldId) is a validated direct join. Routing is capacity- and start-aware, and skips the player's current server.

Request body

application/json

{
  "playerUuid": "string",
  "playerName": "string",
  "serverType": "string",
  "worldType": "string",
  "serverId": "string",
  "worldId": "string",
  "directJoin": false,
  "worldMatchmaking": false
}

Responses

200 A match result. On failure, success=false and result carries the reason.
400 Bad Request

200 response

{
  "success": false,
  "result": "SUCCESS",
  "errorMessage": "string",
  "matchedServer": {
    "serverId": "string",
    "serverType": "string",
    "gameType": "MINECRAFT",
    "displayName": "string",
    "currentPlayers": 0,
    "maxPlayers": 0,
    "host": "string",
    "port": 0,
    "startedAt": 0,
    "lastHeartbeat": 0,
    "gameState": "IDLE",
    "playersToStart": 0,
    "worlds": [
      {
        "worldId": "string",
        "displayName": "string",
        "currentPlayers": 0,
        "maxPlayers": 0,
        "gameState": "IDLE",
        "playersToStart": 0,
        "worldType": "string",
        "full": false,
        "playerCountDisplay": "string",
        "joinable": false,
        "minigameWorld": false,
        "playersNeededToStart": 0
      }
    ],
    "full": false,
    "playerCountDisplay": "string",
    "joinable": false,
    "minigameServer": false,
    "playersNeededToStart": 0,
    "totalPlayers": 0
  },
  "matchedWorld": {
    "worldId": null,
    "displayName": null,
    "currentPlayers": null,
    "maxPlayers": null,
    "gameState": "IDLE",
    "playersToStart": null,
    "worldType": null,
    "full": null,
    "playerCountDisplay": null,
    "joinable": null,
    "minigameWorld": null,
    "playersNeededToStart": null
  },
  "transferId": "string"
}

Request

curl -X POST http://localhost:8090/api/plugin/matchmaking/find \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerUuid":"string","playerName":"string","serverType":"string","worldType":"string","serverId":"string","worldId":"string","directJoin":false,"worldMatchmaking":false}'

// Best server of a type (capacity- and start-aware):
hive.matchmaking().findServer(uuid, name, "skywars").thenAccept(r -> {
  if (r.isSuccess()) {
    hive.transfer().transfer(uuid, r.getMatchedServer().getServerId(), null);
  } else {
    // r.getResult(): NO_SERVERS_AVAILABLE, ALL_SERVERS_FULL, ...
  }
});

// Instanced game (best world of a type), or a direct join:
hive.matchmaking().findServerWithWorld(uuid, name, "skywars", "ranked");
hive.matchmaking().joinServer(uuid, name, "lobby-2");
hive.matchmaking().joinServerWorld(uuid, name, "skywars-3", "arena-7");