Documentation menu

API Reference

Manage: Servers

API-key control of managed servers (list, power, console, commands)

GET /api/manage/servers

List this network's servers

Every known server, online and offline, paginated. Spans proxies as well as game servers, so read `role` to tell them apart. Each row carries `control`, which is non-null exactly when a node agent is connected and reporting that server's container: that is what says whether power and console will work on it. Filters: ?serverType, ?online=true|false, ?search, ?region.

Parameters

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

Responses

  • 200 A page of servers.
  • 403 The key does not carry the 'servers:read' scope.
200 response 
{
  "items": [
    {
      "serverId": "string",
      "serverType": "string",
      "gameType": "string",
      "role": "string",
      "connectivity": "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,
        "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
      },
      "geoRegion": "string",
      "geoCountry": "string",
      "control": {
        "nodeId": "string",
        "capabilities": [
          "string"
        ],
        "containerState": "string",
        "containerStatus": "string",
        "exitCode": 0,
        "outOfMemory": false
      },
      "buildInfo": {
        "version": "string",
        "build": 0,
        "commit": "string"
      },
      "platform": {
        "name": "string",
        "version": "string"
      },
      "ports": [
        {
          "port": 0,
          "protocol": "string",
          "adopted": false
        }
      ],
      "provisioned": false
    }
  ],
  "page": 0,
  "limit": 0,
  "total": 0
}

Request

~
curl -X GET https://api.beehivesys.net/api/manage/servers?limit=0&online=0&page=0&region=value&search=value&serverType=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers?limit=0&online=0&page=0&region=value&search=value&serverType=value"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

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

Get one server

The durable record joined with live presence and, when a node agent is reporting it, its container state and the ports it holds.

Parameters

  • serverId string path required

    Server id.

Responses

  • 200 The server.
  • 404 No server with that id on this network.
200 response 
{
  "serverId": "string",
  "serverType": "string",
  "gameType": "string",
  "role": "string",
  "connectivity": "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,
    "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
  },
  "geoRegion": "string",
  "geoCountry": "string",
  "control": {
    "nodeId": "string",
    "capabilities": [
      "string"
    ],
    "containerState": "string",
    "containerStatus": "string",
    "exitCode": 0,
    "outOfMemory": false
  },
  "buildInfo": {
    "version": "string",
    "build": 0,
    "commit": "string"
  },
  "platform": {
    "name": "string",
    "version": "string"
  },
  "ports": [
    {
      "port": 0,
      "protocol": "string",
      "adopted": false
    }
  ],
  "provisioned": false
}

Request

~
curl -X GET https://api.beehivesys.net/api/manage/servers/{serverId} \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

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

Run a command inside a server and get its output

Pushed to the connector over its event stream and run as console, with whatever the command printed returned. Needs the server online with the Hive connector; it does NOT need a node agent, so it works on a server the operator hosts themselves. Waits ?timeoutMs (default 10000, max 60000) for the reply.

Parameters

  • serverId string path required

Request body

application/json 
{
  "command": "string",
  "timeoutMs": 0
}

Responses

  • 200 The command's output.
  • 400 Missing command.
  • 403 The key does not carry the 'servers:control' scope.
  • 503 The server is not connected, or did not answer in time.
200 response 
{
  "success": false,
  "output": "string",
  "error": "string"
}

Request

~
curl -X POST https://api.beehivesys.net/api/manage/servers/{serverId}/command \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"string","timeoutMs":0}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"command\":\"string\",\"timeoutMs\":0}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}/command"))
    .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/manage/servers/{serverId}/console

Write a line to a server's stdin

Goes to the container through the node agent, so it reaches a server whose plugin is wedged or not installed. Returns only whether the write landed. To get a command's output back, use /command, or read /logs afterwards.

Parameters

  • serverId string path required

Request body

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

Responses

  • 200 The agent's result (ok / error).
  • 400 Missing line.
  • 403 The key does not carry the 'servers:control' scope.
  • 404 No connected node hosts this server.
  • 503 The node is not connected, or did not respond.
200 response 
{
  "ok": false,
  "error": "string",
  "data": {}
}

Request

~
curl -X POST https://api.beehivesys.net/api/manage/servers/{serverId}/console \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"line":"string"}'
HttpClient client = HttpClient.newHttpClient();

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

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}/console"))
    .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/manage/servers/{serverId}/kill

Kill a server immediately (no clean shutdown)

SIGKILLs the container. The server gets no chance to save, so anything it had not already persisted is lost, and a world mid-write can be left needing a snapshot restore. Use /stop unless the server is unresponsive.

Parameters

  • serverId string path required

Responses

  • 200 The agent's result (ok / error).
  • 403 The key does not carry the 'servers:control' scope.
  • 404 No connected node agent hosts this server.
  • 503 The node is not connected, or did not respond.
200 response 
{
  "ok": false,
  "error": "string",
  "data": {}
}

Request

~
curl -X POST https://api.beehivesys.net/api/manage/servers/{serverId}/kill \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}/kill"))
    .header("X-Hive-Api-Key", apiKey)
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

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

Read the tail of a server's console

The last ?lines of stdout/stderr (default 200, max 5000), read once and returned. This is the automation-shaped counterpart to the dashboard's live console stream: ask, get an answer, done. Requires a connected node agent.

Parameters

  • serverId string path required
  • lines integer query

Responses

  • 200 The console tail.
  • 403 The key does not carry the 'servers:read' scope.
  • 404 No connected node hosts this server.
  • 503 The node is not connected, or did not deliver in time.
200 response 
{
  "serverId": "string",
  "content": "string"
}

Request

~
curl -X GET https://api.beehivesys.net/api/manage/servers/{serverId}/logs?lines=0 \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}/logs?lines=0"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

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

Restart a server

Stops the container cleanly, then starts it again. NOT refused because players are on it or a match is running: read `live.gameState` first if that matters, since nothing else will stop you ending a round halfway through.

Parameters

  • serverId string path required

Responses

  • 200 The agent's result (ok / error).
  • 403 The key does not carry the 'servers:control' scope.
  • 404 No connected node agent hosts this server.
  • 503 The node is not connected, or did not respond.
200 response 
{
  "ok": false,
  "error": "string",
  "data": {}
}

Request

~
curl -X POST https://api.beehivesys.net/api/manage/servers/{serverId}/restart \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}/restart"))
    .header("X-Hive-Api-Key", apiKey)
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

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

Start a server

Starts the server's container through its node agent. A no-op result rather than an error if it is already running.

Parameters

  • serverId string path required

Responses

  • 200 The agent's result (ok / error).
  • 403 The key does not carry the 'servers:control' scope.
  • 404 No connected node agent hosts this server.
  • 503 The node is not connected, or did not respond.
200 response 
{
  "ok": false,
  "error": "string",
  "data": {}
}

Request

~
curl -X POST https://api.beehivesys.net/api/manage/servers/{serverId}/start \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}/start"))
    .header("X-Hive-Api-Key", apiKey)
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

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

Stop a server cleanly

Signals the container to shut down cleanly, giving the server a chance to save. Returns once the agent has signalled it, NOT once the game has finished stopping: poll GET /api/manage/servers/{serverId} if you need to know it is down.

Parameters

  • serverId string path required

Responses

  • 200 The agent's result (ok / error).
  • 403 The key does not carry the 'servers:control' scope.
  • 404 No connected node agent hosts this server.
  • 503 The node is not connected, or did not respond.
200 response 
{
  "ok": false,
  "error": "string",
  "data": {}
}

Request

~
curl -X POST https://api.beehivesys.net/api/manage/servers/{serverId}/stop \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.beehivesys.net/api/manage/servers/{serverId}/stop"))
    .header("X-Hive-Api-Key", apiKey)
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();

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