Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerBridge/llms.txt

Use this file to discover all available pages before exploring further.

The /v2/players endpoint returns the total number of players currently online and a list of their display names. When the online player count exceeds the configured players.max-list limit, the list is truncated but the count field always reflects the true total. This makes it easy to detect that more players are online than the list shows, without needing to fetch them in pages.

​
Request

Method: GET
Path: /v2/players

​
Headers

HeaderRequiredDescription
X-Auth-KeyYesAuthentication key from config.yaml → auth.key

​
Configuration

This endpoint can be disabled in config.yaml under v2-endpoints.players. It is enabled by default. The maximum number of player names returned in the players array is controlled by players.max-list. The default is 50. 
v2-endpoints:
  players: true

players:
  max-list: 50
If v2-endpoints.players is set to false, the server returns a 403 Forbidden response.

​
Response

​
ok
boolean
required
Always true on success.
​
count
integer
required
The total number of players currently online at the moment the request was processed. This value is taken before any truncation, so it may be greater than the number of entries in the players array when more players are online than players.max-list allows.
​
players
string[]
required
An array of player name strings. The list is capped at players.max-list entries (default 50). When more players are online than the limit, the first max-list names from the server’s online-player collection are returned.
  • Fabric: Names are collected from server.getPlayerList().getPlayers() and converted to strings via player.getName().getString().
  • Paper: Names are collected from Bukkit.getOnlinePlayers() and retrieved via player.getName().
The list may be empty ([]) when no players are online.

​
Example Response — Players Online

{
  "ok": true,
  "count": 3,
  "players": [
    "Notch",
    "Dinnerbone",
    "jeb_"
  ]
}

​
Example Response — No Players Online

{
  "ok": true,
  "count": 0,
  "players": []
}

​
Example Response — List Truncated

When 75 players are online but players.max-list is 50: 
{
  "ok": true,
  "count": 75,
  "players": [
    "PlayerOne",
    "PlayerTwo",
    "..."
  ]
}
When count is greater than the length of players, the list has been truncated. The count field always reflects the true total regardless of the limit. Adjust players.max-list in config.yaml to raise or lower the cap.

​
Error Responses

Statuserror fieldCause
401unauthorizedMissing or incorrect X-Auth-Key header
403forbiddenEndpoint disabled via v2-endpoints.players: false
405method_not_allowedRequest method was not GET
{
  "ok": false,
  "error": "unauthorized",
  "message": "Invalid X-Auth-Key"
}

​
curl Example

curl -s -X GET http://localhost:30007/v2/players \
  -H "X-Auth-Key: your-auth-key"

Build docs developers (and LLMs) love

Get started for freeTalk to us