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",
  "region": "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,
    "region": "EUROPE",
    "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 https://api.hivescale.dev/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","region":"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");

GET /api/plugin/matchmaking/regions

List regions with available servers

Region availability for building a manual selector: per region, the number of joinable-tier servers and players, most-populated first. Optional serverType scopes to one game; omit it for the whole network. Servers whose host couldn't be located are grouped under "UNKNOWN". Empty when geo routing is disabled (no .mmdb configured).

Parameters

serverType string query

Scope to one server type; omit for the whole network.

Responses

200 Per-region server + player counts.

200 response

[
  {
    "region": "string",
    "servers": 0,
    "players": 0
  }
]

Request

curl -X GET https://api.hivescale.dev/api/plugin/matchmaking/regions?serverType=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/matchmaking/regions?serverType=value"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());