Services

Services API

The Services API provides endpoints to manage and monitor services in your PoloCloud instance.

Manage services, execute commands, and monitor service statistics via REST API

Service Count

Get the total count of services with optional time range filtering and percentage calculations.

Endpoint: GET /polocloud/api/v3/services/count

Query Parameters:

from (optional) - Start timestamp for range filtering
to (optional) - End timestamp for range filtering

Response (Total Count):

{
  "status": 200,
  "data": {
    "serviceCount": 15
  }
}

Response (With Range):

{
  "status": 200,
  "data": {
    "serviceCount": 8,
    "percentage": 12.5
  }
}

Error Responses:

400 - Invalid range

List Services

Retrieve all services with their detailed information.

Endpoint: GET /polocloud/api/v3/services/list

Response:

{
  "status": 200,
  "data": [
    {
      "name": "lobby-1",
      "state": "ONLINE",
      "type": "SERVER",
      "groupName": "lobby",
      "hostname": "127.0.0.1",
      "port": 30000,
      "templates": [
        {
          "name": "EVERY",
          "size": "unknown"
        },
        {
          "name": "EVERY_SERVER",
          "size": "unknown"
        },
        {
          "name": "EVERY_FALLBACK",
          "size": "unknown"
        },
        {
          "name": "lobby",
          "size": "unknown"
        }
      ],
      "properties": {
        "fallback": "true"
      },
      "minMemory": 1024,
      "maxMemory": 1024,
      "playerCount": 1,
      "maxPlayerCount": 20,
      "memoryUsage": 1706.0,
      "cpuUsage": 0.21,
      "motd": "Polocloud 😊"
    },
    {
      "name": "proxy-1",
      "state": "STARTING",
      "type": "PROXY",
      "groupName": "proxy",
      "hostname": "0.0.0.0",
      "port": 25565,
      "templates": [
        {
          "name": "EVERY",
          "size": "unknown"
        },
        {
          "name": "EVERY_PROXY",
          "size": "unknown"
        },
        {
          "name": "proxy",
          "size": "unknown"
        }
      ],
      "properties": {},
      "minMemory": 512,
      "maxMemory": 512,
      "playerCount": -1,
      "maxPlayerCount": -1,
      "memoryUsage": 556.0,
      "cpuUsage": 0.04,
      "motd": ""
    }
  ]
}

Execute Command

Execute a command on a specific service.

Endpoint: POST /polocloud/api/v3/service/{serviceName}/command

Parameters:

serviceName (path) - The name of the service to execute the command on

Request Body:

{
  "command": "say Hello from API!"
}

Response:

{
  "status": 200,
  "message": "Trying to execute command on service"
}

Error Responses:

400 - Command is required
404 - Service not found

Restart Service

Restart a specific service.

Endpoint: PATCH /polocloud/api/v3/service/{serviceName}/restart

Parameters:

serviceName (path) - The name of the service to restart

Response:

{
  "status": 202,
  "message": "Service is restarting"
}

Error Responses:

404 - Service not found

Service Model

Field	Type	Description
`name`	string	Unique service name
`state`	string	Current service state (ONLINE, OFFLINE, STARTING, STOPPING)
`type`	string	Service type (SERVER, PROXY)
`groupName`	string	Name of the group this service belongs to
`hostname`	string	Hostname/IP address the service is bound to
`port`	number	Network port the service is running on
`templates`	array	List of applied templates with name and size
`properties`	object	Service-specific configuration properties
`minMemory`	number	Minimum memory allocation in MB
`maxMemory`	number	Maximum memory allocation in MB
`playerCount`	number	Current number of players online (-1 for PROXY)
`maxPlayerCount`	number	Maximum number of players allowed (-1 for PROXY)
`memoryUsage`	number	Current memory usage in MB
`cpuUsage`	number	Current CPU usage percentage
`motd`	string	Message of the day displayed to players

Usage Examples

Get Total Service Count

curl -X GET "http://localhost:8080/polocloud/api/v3/services/count" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Get Service Count in Range

curl -X GET "http://localhost:8080/polocloud/api/v3/services/count?from=1757600000000&to=1757609999999" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

List All Services

curl -X GET "http://localhost:8080/polocloud/api/v3/services/list" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Execute Command on Service

curl -X POST "http://localhost:8080/polocloud/api/v3/service/lobby-1/command" \
  -H "Content-Type: application/json" \
  -H "Cookie: token=YOUR_TOKEN_HERE" \
  -d '{
    "command": "say Hello from API!"
  }'

Restart Service

curl -X PATCH "http://localhost:8080/polocloud/api/v3/service/lobby-1/restart" \
  -H "Cookie: token=YOUR_TOKEN_HERE"

Services

On this page