The ForestBot Hub serves as the backbone for connecting all ForestBot instances, facilitating real-time data exchange and providing REST API endpoints for comprehensive server and player data.
ForestBot Hub is a centralized API and data processing service designed to manage, analyze, and serve Minecraft server data. It provides seamless WebSocket-based communication for real-time updates and powerful REST API endpoints for fetching and managing server statistics.
- Enables bi-directional, real-time communication with connected ForestBot instances.
- Transmits live data, including:
- Player kills
- Messages sent
- Player deaths
- Player joins and leaves
For more details on how WebSocket communication works within ForestBot, refer to the WebSocket Documentation.
- Compiles and serves real-time tablist data for connected servers.
- Provides access to detailed server and player statistics.
- Supports fetching specific player data, server analytics, and leaderboard information.
- Handles all database operations, ensuring efficient and reliable data storage.
- Manages player sessions, recording:
- Join and leave times
- Total playtime
- Player activity stats
- Tracks individual player sessions for granular data, enabling features like:
- Daily activity breakdowns
- Historical data analysis
- Node.js (version 20.x.x or higher)
- A running MariaDB instance for data storage
- Web server or reverse proxy for serving the API
API URL: https://api.forestbot.org
Website URL: https://forestbot.org
- GET /advancements?uuid=&server=&limit=&order=
- GET /advancements-count?uuid=&server=
- GET /all-servers
- GET /all-user-stats?uuid=
- GET /convert-username-to-uuid?username=
- GET /deaths?uuid=&server=&limit=&order=&type=
- GET /faq?id=&server=
- GET /player/playtime?uuid=&date=&server=
- GET /kills?uuid=&server=&limit=&order=
- GET /messagecount?username=&server=
- GET /messages?name=&server=&limit=&order=
- GET /namesearch?user=<search_term>&server=
- GET /online?user=
- GET /quote?name=&server=
- GET /tab/:server
- GET /top-statistic?statistic=&server=&limit=
- GET /user?server=&uuid=
- GET /users-sorted-by-joindate?server=&order=&limit=&usernames=
- GET /whois?username=
- GET /wordcount?word=&server=&username=
GET /advancements?uuid=&server=&limit=&order=
Retrieves a user's advancements on a specific server.
Response Example:
{
"username": "player123",
"advancement": "First Steps",
"time": 1616161616161,
"mc_server": "server1",
"uuid": "player-uuid"
}
GET /advancements-count?uuid=&server=
Gets the total advancement count for a user on a specific server.
Response Example:
{
"total": 5
}
GET /all-servers
Gets a list of all available servers in the database.
Response Example:
[
{ "mc_server": "server1" },
{ "mc_server": "server2" }
]
GET /all-user-stats?uuid=
Gets a comprehensive list of stats for a specific user across all servers.
Response Example:
[
{
"username": "player123",
"kills": 20,
"deaths": 10,
"joindate": "2021-01-01T12:00:00Z",
"lastseen": "2021-12-01T12:00:00Z",
"UUID": "player-uuid",
"playtime": 1200,
"joins": 15,
"leaves": 14,
"lastdeathTime": 1616161616161,
"lastdeathString": "Killed by skeleton",
"mc_server": "server1"
}
]
GET /convert-username-to-uuid?username=
Converts a username to a UUID using the ForestBot database.
Response Example:
{
"uuid": "player-uuid"
}
GET /deaths?uuid=&server=&limit=&order=&type=
Retrieves all death records for a user, filtered by type (PvP/PvE).
Response Example:
{
"victim": "player123",
"death_message": "Killed by zombie",
"time": 1616161616161,
"type": "pve",
"mc_server": "server1",
"victimUUID": "player-uuid"
}
GET /faq?id=&server=
Retrieves a random FAQ entry from the database.
Response Example:
{
"username": "admin",
"uuid": "admin-uuid",
"server": "server1",
"id": 123,
"faq": "How to play on the server?",
"timestamp": "2021-12-01T12:00:00Z",
"total": 5
}
GET /player/playtime?uuid=&date=&server=
Gets historical playtime data for a specific user on a specific server.
Response Example:
{
"day": "2021-12-01",
"playtime": 120
}
GET /kills?uuid=&server=&limit=&order=
Gets all kill records for a user.
Response Example:
{
"victim": "player456",
"death_message": "Killed by player123",
"time": 1616161616161,
"type": "pvp",
"mc_server": "server1",
"victimUUID": "player-uuid"
}
GET /messagecount?username=&server=
Gets the number of messages sent by a user on a specific server.
Response Example:
{
"count": 42
}
GET /messages?name=&server=&limit=&order=
Retrieves all messages sent by a user on a server.
Response Example:
{
"name": "player123",
"message": "Hello!",
"date": "2021-12-01T12:00:00Z",
"mc_server": "server1",
"uuid": "player-uuid"
}
GET /namesearch?user=<search_term>&server=
Gets likely usernames related to your search term.
Response Example:
[
"player123",
"player456",
"player789"
]
GET /online?user=
Checks if a user is online and which server they are on.
Response Example:
{
"online": true,
"server": "server1"
}
GET /quote?name=&server=
Gets a random quoted message from a user.
Response Example:
{
"message": "Hello world!",
"date": "2021-12-01T12:00:00Z"
}
GET /tab/:server
Gets a live tablist image for a specific server.
Response Example:
A live image representing the current tablist.
GET /top-statistic?statistic=&server=&limit=
Gets the top 5 users in a specific statistic on a server.
Response Example:
[
{ "username": "player123", "statistic": 100 },
{ "username": "player456", "statistic": 90 },
{ "username": "player789", "statistic": 85 }
]
GET /user?server=&uuid=
Gets stats for a specific user on a specific server.
Response Example:
{
"username": "player123",
"kills": 20,
"deaths": 10,
"joindate": "2021-01-01T12:00:00Z",
"lastseen": "2021-12-01T12:00:00Z",
"uuid": "player-uuid",
"playtime": 1200,
"joins": 15,
"leaves": 14,
"lastdeathTime": 1616161616161,
"lastdeathString": "Killed by skeleton",
"mc_server": "server1"
}
GET /whois?username=
Gets the description of a user.
Response Example:
{
"username": "player123",
"description": "A dedicated player who loves exploring."
}
GET /wordcount?word=&server=&username=
Gets the count of how many times a user has sent a specific word.
Response Example:
{
"count": 10
}