Documentation menu

API Reference

Worlds

On-demand player/team worlds (lease + boot + snapshot)

POST /api/plugin/worlds/open

Open (lease + boot if needed) a single-owner world

Returns READY if the owner's world is already live on a node, else LOADING while the hub boots it on the chosen node. Poll/await the world-ready event, then route.

Request body

application/json 
{
  "ownerScope": "string",
  "ownerId": "string",
  "gameId": "string",
  "worldKey": "string",
  "preferNode": "string",
  "seed": {
    "ref": "string",
    "format": "string",
    "x": 0,
    "y": 0,
    "z": 0
  },
  "persistence": "string",
  "worldGen": "string"
}

Responses

  • 200 OK
  • 400 Bad Request
200 response 
{
  "success": false,
  "status": "string",
  "worldInstanceId": "string",
  "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
  },
  "transferId": "string"
}

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/worlds/open \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ownerScope":"string","ownerId":"string","gameId":"string","worldKey":"string","preferNode":"string","seed":{"ref":"string","format":"string","x":0,"y":0,"z":0},"persistence":"string","worldGen":"string"}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"ownerScope\":\"string\",\"ownerId\":\"string\",\"gameId\":\"string\",\"worldKey\":\"string\",\"preferNode\":\"string\",\"seed\":{\"ref\":\"string\",\"format\":\"string\",\"x\":0,\"y\":0,\"z\":0},\"persistence\":\"string\",\"worldGen\":\"string\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/worlds/open"))
    .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/worlds/{id}/heartbeat

Node callback: renew lease, defer idle eviction

Parameters

  • id integer path required

Request body

application/json 
{
  "nodeServerId": "string",
  "fence": 0,
  "playerCount": 0
}

Responses

  • 200 OK
  • 400 Bad Request

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/worlds/{id}/heartbeat \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeServerId":"string","fence":0,"playerCount":0}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"nodeServerId\":\"string\",\"fence\":0,\"playerCount\":0}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/worlds/{id}/heartbeat"))
    .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/worlds/{id}/ready

Node callback: world booted and ready

Parameters

  • id integer path required

Request body

application/json 
{
  "nodeServerId": "string",
  "fence": 0
}

Responses

  • 200 OK
  • 400 Bad Request

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/worlds/{id}/ready \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeServerId":"string","fence":0}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"nodeServerId\":\"string\",\"fence\":0}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/worlds/{id}/ready"))
    .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/worlds/{id}/release

Hint a world is idle so it can be drained

Parameters

  • id integer path required

Responses

  • 200 OK

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/worlds/{id}/release \
  -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/worlds/{id}/release"))
    .header("X-Hive-Api-Key", apiKey)
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
POST /api/plugin/worlds/{id}/snapshot

Force a save point on a live world

Parameters

  • id integer path required

Request body

application/json 
{
  "reason": "string"
}

Responses

  • 200 OK
  • 400 Bad Request

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/worlds/{id}/snapshot \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string"}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"reason\":\"string\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/worlds/{id}/snapshot"))
    .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/worlds/{id}/unloaded

Node callback: snapshot + unload complete

Parameters

  • id integer path required

Request body

application/json 
{
  "nodeServerId": "string",
  "blobKey": "string",
  "fence": 0
}

Responses

  • 200 OK
  • 400 Bad Request

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/worlds/{id}/unloaded \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodeServerId":"string","blobKey":"string","fence":0}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"nodeServerId\":\"string\",\"blobKey\":\"string\",\"fence\":0}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/worlds/{id}/unloaded"))
    .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/worlds/{id}/upload-url

Node callback: mint a presigned PUT URL for a cloud-tier snapshot

Parameters

  • id integer path required

Responses

  • 200 OK

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/worlds/{id}/upload-url \
  -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/worlds/{id}/upload-url"))
    .header("X-Hive-Api-Key", apiKey)
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

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