API Reference

Transfers

Move players between servers

POST /api/plugin/transfers

Move a player to another server

Resolves the player's current server and the target host/port, then pushes a signed transfer command to the owning server over the event stream.

Request body

application/json

{
  "playerUuid": "string",
  "targetServerId": "string",
  "targetWorldId": "string"
}

Responses

200 The transfer outcome, correlated by transferId.
400 Bad Request

200 response

{
  "transferId": "string",
  "playerUuid": "string",
  "result": "SUCCESS",
  "errorMessage": "string",
  "success": false
}

Request

curl -X POST http://localhost:8090/api/plugin/transfers \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerUuid":"string","targetServerId":"string","targetWorldId":"string"}'

// Move a player to another server (worldId optional).
hive.transfer().transfer(playerUuid, "lobby-1", null).thenAccept(r -> {
  if (r.isSuccess()) { /* r.transferId() */ }
});

POST /api/plugin/transfers/result

Report a transfer outcome

The receiving server reports whether the referral succeeded, closing the loop on a transfer initiated elsewhere.

Request body

application/json

{
  "transferId": "string",
  "playerUuid": "string",
  "result": "string",
  "errorMessage": "string"
}

Responses

204 Outcome recorded.
400 Bad Request

Request

curl -X POST http://localhost:8090/api/plugin/transfers/result \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transferId":"string","playerUuid":"string","result":"string","errorMessage":"string"}'

// The receiving server reports the outcome back to the hub.
hive.transfer().reportResult(transferId, playerUuid, "SUCCESS", null);