# Velocity Web API<\/p>\n
\n<\/p>\n
<\/p>\n
Lightweight HTTP API for Velocity proxies. Expose player lists, per-server counts, per-player details, etc. Ideal for websites, bots or other monitoring applications. I built it for my own uses, but it might help someone else out too.<\/p>\n
## Quick Install<\/p>\n
– Drop the compiled plugin JAR into your Velocity `plugins\/` folder.
\n– Start (or restart) your proxy; the plugin will create its data folder and a `config.cfg` (if missing) in the plugin data directory.<\/p>\n
## Configuration<\/p>\n
– The plugin creates a `config.cfg` in its data folder on first run. Available keys:
\n\t– `port` : port the HTTP server listens on (default `25576`).
\n\t– `bindAddress` : interface\/address to bind the HTTP server (default `0.0.0.0` to listen on all IPv4 interfaces; set to `127.0.0.1` for local-only access).
\n\t– `checkUpdates` : enable automatic Hangar update checks (default `true`).
\n\t– `snapshotUpdates` : include snapshot\/unstable updates in checks (default `false`).
\n\t– `debugEnabled` : show debug messages (`logger.debug`) in the proxy console when `true` (default `false`).
\n\t– `allowedOrigins` : CORS allowed origins for HTTP API access (comma-separated, or * for all) (default `*`).<\/p>\n
## Tested With<\/p>\n
– Velocity 3.x (expects `velocity-api` on the runtime classpath)<\/p>\n
## Endpoints<\/p>\n
All JSON endpoints return `Content-Type: application\/json; charset=utf-8` unless otherwise noted.<\/p>\n
– `\/`
\n\t– Serves the embedded `index.html` (browser-friendly).
\n\t– Example URL: `http:\/\/localhost:25576\/` <\/p>\n
– `\/playerlist`
\n\t– Purpose: list connected players with basic metadata and a total count.
\n\t– Example URL: `http:\/\/localhost:25576\/playerlist`
\n\t– Sample response:<\/p>\n
\t“`json
\n\t{
\n\t\t“count”: 2,
\n\t\t“players”:
\n\t\t[
\n\t\t\t{“username”:”Alice”,”uuid”:”…”,”currentServer”:”lobby”},
\n\t\t\t{“username”:”Bob”,”uuid”:”…”,”currentServer”:”minigames”}
\n\t\t]
\n\t}
\n\t“`<\/p>\n
– `\/count`
\n\t– Purpose: return the total number of connected players.
\n\t– Example URL: `http:\/\/localhost:25576\/count`
\n\t– Sample response:
\n\t“`json
\n\t{
\n\t\t“count”: 42
\n\t}
\n\t“`<\/p>\n
– `\/player\/ \t“`json – `\/servers` – `\/health` ## Commands<\/p>\n – `\/vwapi reload` : reloads the `config.cfg` from the plugin data directory and restarts the HTTP server if the `port` or `bindAddress` have changed. ## Permissions<\/p>\n – `vwapi.admin` : required to use the `\/vwapi` commands.<\/p>\n ## Notes & Behavior<\/p>\n – Player lookup is exact-case and only returns connected players. ## Troubleshooting<\/p>\n – If the HTTP server does not start, check the proxy logs for errors about port binding or resource issues. ## License & Support<\/p>\n – Licensed under the MIT License. A plugin to expose web API endpoints for Velocity proxy servers. Display player and server information easily.<\/p>\n","protected":false},"featured_media":165572,"template":"","meta":{"_minecraft_slug":"velocity-web-api","_minecraft_project_id":"RBlrF608","_minecraft_author":"skrrtn","_minecraft_license":"MIT","_minecraft_downloads":68,"_minecraft_follows":3,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"velocity-web-api.zip","_minecraft_size_bytes":44161,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T20:31:30.485500Z","_minecraft_date_created":"2025-11-25T02:43:37.261166Z","_minecraft_date_modified":"2025-11-25T02:06:16.014983Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/velocity-web-api","_minecraft_icon_attachment_id":165572,"_minecraft_imported_at":"2026-06-09T17:50:47+00:00","_minecraft_import_hash":"b043cf698bcb90540e5fbdd4b1cd455d","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[92,985],"mod_loader":[986],"minecraft_version":[339,340,341,357,359,360,379,382,385,438,446,449,110,111,112,113,114,115,116,117,118,119,120,46,47,48,49,50,51,52,53,54,55,56,57,58,59,36,60,93,94,101,102,62,37,40,73,74,38,78,79,80,81,82,22,23,24,25,26,27,28,29,30,31,860,861,862,863,864],"class_list":["post-165571","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-utility","mod_category-velocity","mod_loader-velocity","minecraft_version-1-10","minecraft_version-1-10-1","minecraft_version-1-10-2","minecraft_version-1-11","minecraft_version-1-11-1","minecraft_version-1-11-2","minecraft_version-1-12","minecraft_version-1-12-1","minecraft_version-1-12-2","minecraft_version-1-13","minecraft_version-1-13-1","minecraft_version-1-13-2","minecraft_version-1-14","minecraft_version-1-14-1","minecraft_version-1-14-2","minecraft_version-1-14-3","minecraft_version-1-14-4","minecraft_version-1-15","minecraft_version-1-15-1","minecraft_version-1-15-2","minecraft_version-1-16","minecraft_version-1-16-1","minecraft_version-1-16-2","minecraft_version-1-16-3","minecraft_version-1-16-4","minecraft_version-1-16-5","minecraft_version-1-17","minecraft_version-1-17-1","minecraft_version-1-18","minecraft_version-1-18-1","minecraft_version-1-18-2","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-1-8","minecraft_version-1-8-1","minecraft_version-1-8-2","minecraft_version-1-8-3","minecraft_version-1-8-4","minecraft_version-1-8-5","minecraft_version-1-8-6","minecraft_version-1-8-7","minecraft_version-1-8-8","minecraft_version-1-8-9","minecraft_version-1-9","minecraft_version-1-9-1","minecraft_version-1-9-2","minecraft_version-1-9-3","minecraft_version-1-9-4"],"yoast_head":"\n
\n\t– Purpose: fetch detailed info for a connected player (exact-case lookup).
\n\t– Example URLs:
\n\t\t– `http:\/\/localhost:25576\/player\/Notch`
\n\t\t– `http:\/\/localhost:25576\/player?username=Notch`
\n\t– Notes: returns `400` if username is missing; `404` if the player is not connected.
\n\t– Sample response:<\/p>\n
\n\t{
\n\t\t“username”:”Notch”,
\n\t\t“uuid”:”…”,
\n\t\t“currentServer”:”lobby”,
\n\t\t“ping”:42,
\n\t\t“sessionDurationSeconds”:360
\n\t}
\n\t“`<\/p>\n
\n\t– Purpose: returns a mapping of server names to player counts.
\n\t– Example URL: `http:\/\/localhost:25576\/servers`
\n\t– Sample response:
\n\t“`json
\n\t{
\n\t\t“lobby”: 5,
\n\t\t“minigames”: 12
\n\t}
\n\t“`<\/p>\n
\n\t– Purpose: lightweight health check for monitoring.
\n\t– Example URL: `http:\/\/localhost:25576\/health`
\n\t– Sample response:
\n\t“`json
\n\t{
\n\t\t“status”: “ok”
\n\t}
\n\t“`<\/p>\n
\n– `\/vwapi version` : prints the plugin version (from the plugin metadata).
\n– `\/vwapi debug [on|off]` : toggle or explicitly set debug logging at runtime. When enabled, the plugin prints detailed debug messages and HTTP access lines to the console.
\n– `\/vwapi status` : shows the current HTTP server status (running\/not running), the bound host and port, and an example URL you can visit (falls back to `localhost` when bound to all interfaces).
\n– `\/vwapi help` : prints a short help listing the available `\/vwapi` subcommands and usage examples.<\/p>\n
\n– The HTTP server binds to `bindAddress`; by default this is `0.0.0.0` (all interfaces). Change to `127.0.0.1` for local-only access or a specific IP if desired.
\n– When you change `bindAddress` or `port` and run `\/vwapi reload`, the plugin will restart the HTTP server automatically to apply the new bind\/port (a full proxy restart is no longer required for those changes).<\/p>\n
\n– Ensure `velocity-api` is available at runtime and that the plugin is placed in the correct `plugins\/` folder.<\/p>\n
\n– If you need any help or support, please contact me on our Discord.<\/p>\n","protected":false},"excerpt":{"rendered":"