Public REST API for accessing Lavalink node information. Real-time data, zero authentication required.
/api/v1/nodes
Returns all currently online Lavalink nodes with complete connection details. Perfect for music bots looking for available nodes to connect to.
{
"nodes": [
{
"name": "My Node",
"host": "lavalink.example.com",
"port": 443,
"password": "youshallnotpass",
"secure": true,
"version": "v4",
"ping": 45,
"players": 12,
"uptime": "3d 12h 45m",
"source": "github",
"authorId": "username"
}
],
"total": 1,
"updated": "2024-01-15T10:30:00.000Z"
}/api/v1/nodes/ssl
Returns only SSL-secured nodes (wss://). Recommended for production environments where encryption is required.
{
"nodes": [
{
"host": "lavalink.example.com:443",
"password": "youshallnotpass",
"identifier": "My Node"
}
],
"total": 1
}/api/v1/nodes/non-ssl
Returns only non-SSL nodes (ws://). Useful for local development or internal networks where encryption isn't needed.
/api/v1/random
Returns a single random online node. Ideal for load balancing and auto-failover implementations where you want to distribute connections.
{
"name": "Random Node",
"host": "lavalink.example.com",
"port": 443,
"password": "youshallnotpass",
"secure": true,
"ping": 32,
"version": "4.0.0"
}/api/v1/best
Returns the best available node based on a scoring algorithm that considers ping (40%), CPU load (40%), and player count (20%). Perfect for getting optimal performance.
{
"name": "Best Node",
"host": "lavalink.example.com",
"port": 443,
"password": "youshallnotpass",
"secure": true,
"ping": 15,
"score": 95,
"metrics": {
"ping": 15,
"cpu": 12,
"players": 3
}
}/api/v1/stats
Returns global statistics about all monitored nodes including online count, average metrics, source distribution, and server health.
{
"total_nodes": 50,
"online_nodes": 42,
"offline_nodes": 8,
"total_players": 156,
"sources": {
"local": 5,
"public": 25,
"github": 20
},
"average_ping_ms": 85,
"average_cpu_percent": 23,
"uptime_seconds": 86400,
"total_requests": 15234,
"last_updated": "2024-01-15T10:30:00.000Z"
}/api/v1/search?q={query}
Search nodes by name, host, or author ID. Returns matching nodes with their current status.
| Parameter | Type | Required | Description |
|---|---|---|---|
q |
string | Required | Search query (case-insensitive) |
/api/v1/node/:host/:port
Get detailed information about a specific node including 24-hour uptime percentage and historical data.
| Parameter | Type | Required | Description |
|---|---|---|---|
host |
string | Required | Node hostname |
port |
number | Required | Node port |
/api/v1/history/:host/:port?hours=24
Get historical performance data for a specific node. Useful for monitoring trends and uptime analysis.
| Parameter | Type | Required | Description |
|---|---|---|---|
host |
string | Required | Node hostname |
port |
number | Required | Node port |
hours |
number | Optional | Hours of history (default: 24, max: 48) |
/nodes.txt
Plain text list of online nodes (one per line). Compatible with legacy bots and simple parsers.
wss://node1.example.com:443
wss://node2.example.com:443
ws://node3.example.com:2333/health
Health check endpoint for monitoring services like UptimeRobot. Returns 200 if at least one node is online, 503 if all nodes are down.
{
"status": "healthy",
"online_nodes": 42,
"total_nodes": 50,
"uptime_seconds": 86400,
"timestamp": "2024-01-15T10:30:00.000Z"
}