Groups

Groups API

The Groups API allows you to manage service groups in PoloCloud through REST endpoints.

Manage service groups and configurations via REST API

Authentication Required

All group endpoints require authentication. In Postman, add your token in the Cookies tab:

Name: token
Value: your-jwt-token-here

Endpoints

Get Group Count

# Get total group count
curl -X GET "http://localhost:8080/polocloud/api/v3/group/count" -H "Cookie: token=your-jwt-token"

# Get group count in date range
curl -X GET "http://localhost:8080/polocloud/api/v3/group/count?from=1640995200000&to=1672531200000" -H "Cookie: token=your-jwt-token"

Query Parameters:

from (optional): Start timestamp in milliseconds
to (optional): End timestamp in milliseconds

List All Groups

# Get all groups
curl -X GET "http://localhost:8080/polocloud/api/v3/group/list" -H "Cookie: token=your-jwt-token"

Get Specific Group

# Get group by name
curl -X GET "http://localhost:8080/polocloud/api/v3/group/lobby" -H "Cookie: token=your-jwt-token"

Create Group

# Create a new group
curl -X POST "http://localhost:8080/polocloud/api/v3/group/create" -H "Content-Type: application/json" -H "Cookie: token=your-jwt-token" -d '{
  "name": "lobby",
  "minMemory": 512,
  "maxMemory": 1024,
  "minOnlineService": 1,
  "maxOnlineService": 5,
  "platform": {
    "name": "paper",
    "version": "1.20.1"
  },
  "percentageToStartNewService": 80.0,
  "createdAt": 1640995200000,
  "templates": ["lobby-template"],
  "properties": {
    "fallback": true,
    "static": true
  }
}'

Required Fields:

name: Group name (must be unique)
minMemory: Minimum memory in MB
maxMemory: Maximum memory in MB
minOnlineService: Minimum online services
maxOnlineService: Maximum online services
platform.name: Platform name (e.g., "paper", "spigot")
platform.version: Platform version (e.g., "1.20.1")
percentageToStartNewService: Percentage (0.0-100.0)
properties: Static configuration values (strings, booleans, numbers)

Properties

Properties are static configuration values that can be:

Fallback: "fallback": true - Default fallback behavior
Static: "static": true - Static configuration value

All properties fallback to true or false if not specified.

Edit Group

# Edit group settings
curl -X PATCH "http://localhost:8080/polocloud/api/v3/group/lobby" -H "Content-Type: application/json" -H "Cookie: token=your-jwt-token" -d '{
  "minMemory": 1024,
  "maxMemory": 2048,
  "minOnlineService": 2,
  "maxOnlineService": 8,
  "percentageToStartNewService": 85.0
}'

Delete Group

# Delete group
curl -X DELETE "http://localhost:8080/polocloud/api/v3/group/lobby" -H "Cookie: token=your-jwt-token"

Delete Group

Deleting a group will:

Shutdown all running services in the group
Remove the group from storage
This action cannot be undone

Response Examples

Group Count Response

{
  "groupCount": 5,
  "percentage": 25.0
}

Group List Response

[
  {
    "name": "lobby",
    "minMemory": 512,
    "maxMemory": 1024,
    "minOnlineService": 1,
    "maxOnlineService": 5,
    "platform": {
      "name": "paper",
      "version": "1.20.1"
    },
    "percentageToStartNewService": 80.0,
    "createdAt": 1640995200000,
    "templates": ["lobby-template"],
    "properties": {
      "fallback": true,
      "static": true
    }
  }
]

Groups

On this page