Documentation menu

API Reference

Servers

Server registration, heartbeat, presence, and listing

GET /api/plugin/provisioning/agent-script

Download the current on-VM agent script (used by the VM bootstrap to self-update)

Responses

  • 200 OK

Request

~
curl -X GET http://localhost:8090/api/plugin/provisioning/agent-script \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/api/plugin/provisioning/agent-script"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
GET /api/plugin/provisioning/agent-version

Current agent version (sha256) — the running agent polls this to detect updates

Responses

  • 200 OK
200 response 
{
  "sha256": "string"
}

Request

~
curl -X GET http://localhost:8090/api/plugin/provisioning/agent-version \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/api/plugin/provisioning/agent-version"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
GET /api/plugin/provisioning/agent/{serverType}

Download the mods bundle for a server type (used by provisioned VMs at boot)

Parameters

  • serverType string path required

Responses

  • 200 OK

Request

~
curl -X GET http://localhost:8090/api/plugin/provisioning/agent/{serverType} \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/api/plugin/provisioning/agent/{serverType}"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
POST /api/plugin/provisioning/auth-code

Report the current OAuth device-login URL/code for a provisioning server

Sent by a provisioned VM while it waits for the operator to authenticate. Moves the provisioning row to AWAITING_AUTH and stores the latest URL + code for the dashboard to display. No-op once the server has registered.

Request body

application/json 
{
  "serverId": "string",
  "verifyUrl": "string",
  "userCode": "string"
}

Responses

  • 201 Created
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/provisioning/auth-code \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"string","verifyUrl":"string","userCode":"string"}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"serverId\":\"string\",\"verifyUrl\":\"string\",\"userCode\":\"string\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/api/plugin/provisioning/auth-code"))
    .header("X-Hive-Api-Key", apiKey)
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
GET /api/plugin/servers

List all known servers (online + offline), paginated

Durable registry joined with live presence: each row carries identity/config plus an online flag and a live snapshot (when online). Filters: ?serverType, ?online=true|false, ?search (server id / display name).

Parameters

  • limit integer query
  • online boolean query
  • page integer query
  • search string query
  • serverType string query

Responses

  • 200 OK
200 response 
{
  "items": [
    {
      "serverId": "string",
      "serverType": "string",
      "gameType": "string",
      "displayName": "string",
      "maxPlayers": 0,
      "status": "string",
      "lastHost": "string",
      "lastPort": 0,
      "firstSeen": 0,
      "lastSeen": 0,
      "online": false,
      "live": {
        "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
      },
      "provisioning": {
        "provider": "string",
        "phase": "string",
        "desiredState": "string",
        "region": "string",
        "serverVmType": "string",
        "ipv4": "string"
      }
    }
  ],
  "page": 0,
  "limit": 0,
  "total": 0
}

Request

~
curl -X GET http://localhost:8090/api/plugin/servers?limit=0&online=0&page=0&search=value&serverType=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
// Browse known servers (online + offline), 0-based page.
hive.server().listServers("skywars", true /* online */, null, 0, 50)
    .thenAccept(page -> { });
POST /api/plugin/servers/heartbeat

Send a heartbeat

Refreshes liveness and reports current state, worlds and online players. Send periodically; missing heartbeats mark the server offline.

Request body

application/json 
{
  "serverId": "string",
  "serverType": "string",
  "gameState": "string",
  "playersToStart": 0,
  "worlds": [
    {
      "worldId": "string",
      "displayName": "string",
      "currentPlayers": 0,
      "maxPlayers": 0,
      "gameState": "string",
      "playersToStart": 0,
      "worldType": "string"
    }
  ],
  "players": [
    {
      "uuid": "string",
      "name": "string"
    }
  ]
}

Responses

  • 204 Heartbeat accepted.
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/servers/heartbeat \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"string","serverType":"string","gameState":"string","playersToStart":0,"worlds":[{"worldId":"string","displayName":"string","currentPlayers":0,"maxPlayers":0,"gameState":"string","playersToStart":0,"worldType":"string"}],"players":[{"uuid":"string","name":"string"}]}'
// Send periodically to stay live and report state + presence.
hive.server().sendHeartbeat("skywars-1", "skywars",
    "PLAYING", 0, worlds, playersByUuid);
GET /api/plugin/servers/players

List online players

Players currently online, optionally filtered by server type.

Parameters

  • serverType string query

    Optional server-type filter.

Responses

  • 200 OK.
200 response 
[
  {
    "playerUuid": "string",
    "playerName": "string",
    "serverId": "string",
    "serverType": "string"
  }
]

Request

~
curl -X GET http://localhost:8090/api/plugin/servers/players?serverType=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.server().onlinePlayers("skywars").thenAccept(players -> { });
POST /api/plugin/servers/players

Record a player join

Marks a player present on a server. If a transfer was pending, the join completes it as a server switch.

Request body

application/json 
{
  "serverId": "string",
  "serverType": "string",
  "playerUuid": "string",
  "playerName": "string"
}

Responses

  • 204 Recorded.
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/servers/players \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"string","serverType":"string","playerUuid":"string","playerName":"string"}'
hive.server().playerJoin("skywars-1", "skywars", playerUuid, playerName);
POST /api/plugin/servers/players/world

Record a world change

Updates which world/instance a player is in on a server.

Request body

application/json 
{
  "serverId": "string",
  "playerUuid": "string",
  "newWorldId": "string",
  "previousWorldId": "string"
}

Responses

  • 204 Recorded.
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/servers/players/world \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"string","playerUuid":"string","newWorldId":"string","previousWorldId":"string"}'
hive.server().setPlayerWorld("skywars-1", playerUuid, "arena-7", "lobby");
DELETE /api/plugin/servers/players/{playerUuid}

Record a player leave

Removes a player's presence on a server. A leave that is the source of a transfer is collapsed into the switch.

Parameters

  • playerUuid string path required

    Player UUID.

  • serverId string query

Responses

  • 204 Recorded.

Request

~
curl -X DELETE http://localhost:8090/api/plugin/servers/players/{playerUuid}?serverId=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.server().playerLeave("skywars-1", playerUuid);
POST /api/plugin/servers/register

Register a server

Registers a server in the network. The server must advertise a client-reachable host:port so transfers can reference it. A blank host is filled in from the request's remote address; a non-positive port is rejected.

Request body

application/json 
{
  "serverId": "string",
  "serverType": "string",
  "gameType": "string",
  "displayName": "string",
  "maxPlayers": 0,
  "host": "string",
  "port": 0,
  "gameState": "string",
  "playersToStart": 0,
  "worlds": [
    {
      "worldId": "string",
      "displayName": "string",
      "currentPlayers": 0,
      "maxPlayers": 0,
      "gameState": "string",
      "playersToStart": 0,
      "worldType": "string"
    }
  ]
}

Responses

  • 201 Created
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/servers/register \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"string","serverType":"string","gameType":"string","displayName":"string","maxPlayers":0,"host":"string","port":0,"gameState":"string","playersToStart":0,"worlds":[{"worldId":"string","displayName":"string","currentPlayers":0,"maxPlayers":0,"gameState":"string","playersToStart":0,"worldType":"string"}]}'
// Announce this server on startup; it becomes matchmakeable.
hive.server().registerServer("skywars-1", "skywars", GameType.HYTALE,
    "SkyWars #1", 12 /* maxPlayers */, "10.0.0.5", 5520,
    "WAITING", 2 /* playersToStart */, worlds);
POST /api/plugin/servers/unregister

Unregister a server

Removes the server's live presence (e.g. on clean shutdown).

Parameters

  • serverId string query

    Server id.

  • serverType string query

Responses

  • 204 Unregistered.

Request

~
curl -X POST http://localhost:8090/api/plugin/servers/unregister?serverId=value&serverType=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
hive.server().unregisterServer("skywars-1", "skywars");
GET /api/plugin/servers/{serverId}/commands

Drain pending control actions for a server (used by the on-VM agent)

Parameters

  • serverId string path required

Responses

  • 200 OK
200 response 
{
  "commands": [
    "string"
  ]
}

Request

~
curl -X GET http://localhost:8090/api/plugin/servers/{serverId}/commands \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/api/plugin/servers/{serverId}/commands"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
POST /api/plugin/servers/{serverId}/commands/{commandId}/result

Report a file command's result (used by the on-VM agent)

Parameters

  • commandId string path required
  • serverId string path required

Request body

application/json 
{
  "status": "string",
  "error": "string",
  "result": {
    "empty": false,
    "valueNode": false,
    "containerNode": false,
    "missingNode": false,
    "array": false,
    "object": false,
    "nodeType": "ARRAY",
    "pojo": false,
    "number": false,
    "integralNumber": false,
    "floatingPointNumber": false,
    "short": false,
    "int": false,
    "long": false,
    "float": false,
    "double": false,
    "bigDecimal": false,
    "bigInteger": false,
    "textual": false,
    "boolean": false,
    "null": false,
    "binary": false
  }
}

Responses

  • 201 Created
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/servers/{serverId}/commands/{commandId}/result \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"string","error":"string","result":{"empty":false,"valueNode":false,"containerNode":false,"missingNode":false,"array":false,"object":false,"nodeType":"ARRAY","pojo":false,"number":false,"integralNumber":false,"floatingPointNumber":false,"short":false,"int":false,"long":false,"float":false,"double":false,"bigDecimal":false,"bigInteger":false,"textual":false,"boolean":false,"null":false,"binary":false}}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"status\":\"string\",\"error\":\"string\",\"result\":{\"empty\":false,\"valueNode\":false,\"containerNode\":false,\"missingNode\":false,\"array\":false,\"object\":false,\"nodeType\":\"ARRAY\",\"pojo\":false,\"number\":false,\"integralNumber\":false,\"floatingPointNumber\":false,\"short\":false,\"int\":false,\"long\":false,\"float\":false,\"double\":false,\"bigDecimal\":false,\"bigInteger\":false,\"textual\":false,\"boolean\":false,\"null\":false,\"binary\":false}}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/api/plugin/servers/{serverId}/commands/{commandId}/result"))
    .header("X-Hive-Api-Key", apiKey)
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
POST /api/plugin/servers/{serverId}/logs

Ship a batch of console log lines for a server (used by the on-VM agent)

Parameters

  • serverId string path required

Request body

application/json 
{
  "agentVersion": "string",
  "lines": [
    {
      "ts": "string",
      "line": "string"
    }
  ]
}

Responses

  • 201 Created
  • 400 Bad Request

Request

~
curl -X POST http://localhost:8090/api/plugin/servers/{serverId}/logs \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentVersion":"string","lines":[{"ts":"string","line":"string"}]}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"agentVersion\":\"string\",\"lines\":[{\"ts\":\"string\",\"line\":\"string\"}]}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/api/plugin/servers/{serverId}/logs"))
    .header("X-Hive-Api-Key", apiKey)
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

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