{"openapi":"3.1.0","info":{"title":"LobbyVerse API","summary":"Game servers with real players: servers, games, communities and rankings, fake player counts flagged.","description":"Every request needs an API key as `Authorization: Bearer lv_…`; make one at https://lobbyverse.com/account/api-keys. Guides: https://api.lobbyverse.com","termsOfService":"","contact":{"name":"LobbyVerse","url":"https://api.lobbyverse.com","email":"hello@lobbyverse.com"},"license":{"name":"GPL 3.0","url":"https://www.gnu.org/licenses/gpl-3.0.html#license-text"},"version":"1.0"},"servers":[{"url":"https://api.lobbyverse.com","description":"LobbyVerse"}],"paths":{"/v1/games":{"get":{"tags":["Games"],"summary":"Games with servers online","description":"Games with servers online, busiest first, with their real players now.","operationId":"GET_v1_games","responses":{"200":{"description":"Games","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/games/{game}":{"get":{"tags":["Games"],"summary":"A game, by mode and country","description":"A game's servers online and real players now, by mode and by country.","operationId":"GET_v1_games_game","parameters":[{"name":"game","in":"path","description":"Its slug or Steam app id","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"The game","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GameDetailData"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/servers":{"get":{"tags":["Servers"],"summary":"Find servers","description":"Servers online now, busiest first, or nearest first with `near`. Only listed servers, whose player counts\nwere checked against their player lists, unless `status=flagged`.","operationId":"GET_v1_servers","parameters":[{"name":"q","in":"query","description":"Words in the server's name or map","required":false,"schema":{"type":"string"},"style":"form"},{"name":"map","in":"query","description":"Part of the map name","required":false,"schema":{"type":"string"},"style":"form"},{"name":"min_players","in":"query","description":"At least this many real players","required":false,"schema":{"type":"integer"},"style":"form"},{"name":"has_players","in":"query","description":"Only servers with real players","required":false,"schema":{"type":"boolean"},"style":"form"},{"name":"not_full","in":"query","description":"Only servers with a free slot","required":false,"schema":{"type":"boolean"},"style":"form"},{"name":"password","in":"query","description":"`false` for servers without a password","required":false,"schema":{"type":"boolean"},"style":"form"},{"name":"vac","in":"query","description":"Only VAC-secured servers","required":false,"schema":{"type":"boolean"},"style":"form"},{"name":"plugin[]","in":"query","description":"Plugins it runs: SourceMod, AMX Mod X, War3FT…","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form"},{"name":"status","in":"query","description":"`listed` (the default) or `flagged`, the fakes with their reasons","required":false,"schema":{"type":"string"},"style":"form"},{"name":"sort","in":"query","description":"`players` (the default), `name`, or `nearby` with `near`","required":false,"schema":{"type":"string"},"style":"form"},{"$ref":"#/components/parameters/game"},{"$ref":"#/components/parameters/mode"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/tag"},{"$ref":"#/components/parameters/lang"},{"$ref":"#/components/parameters/near"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"A page of servers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerPage"}}}},"400":{"$ref":"#/components/responses/BadParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/servers/{address}":{"get":{"tags":["Servers"],"summary":"A server","description":"A server with everything LobbyVerse knows about it: whether it's flagged and why, its plugins, location and\ncommunity, and links to its players, settings and history.","operationId":"GET_v1_servers_address","parameters":[{"name":"address","in":"path","description":"Address of existing server.","required":true,"schema":{"type":"string"},"style":"simple"},{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"The server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerDetailData"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/servers/{address}/players":{"get":{"tags":["Servers"],"summary":"Who's playing now","description":"Who's playing now, as the server last reported its player list. Names are whatever players chose.","operationId":"GET_v1_servers_address_players","parameters":[{"name":"address","in":"path","description":"Address of existing server.","required":true,"schema":{"type":"string"},"style":"simple"},{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"Its players","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/servers/{address}/rules":{"get":{"tags":["Servers"],"summary":"Its settings","description":"Its settings (cvars) and their values, as the server reports them.","operationId":"GET_v1_servers_address_rules","parameters":[{"name":"address","in":"path","description":"Address of existing server.","required":true,"schema":{"type":"string"},"style":"simple"},{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"Its settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rules"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/servers/{address}/history":{"get":{"tags":["Servers"],"summary":"Real players over time","description":"Real players over time, one point an hour from LobbyVerse's checks, oldest first.","operationId":"GET_v1_servers_address_history","parameters":[{"name":"range","in":"query","description":"`24h` (the default), `7d` or `30d`","required":false,"schema":{"type":"string"},"style":"form"},{"name":"address","in":"path","description":"Address of existing server.","required":true,"schema":{"type":"string"},"style":"simple"},{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"Points in time","content":{"application/json":{"schema":{"$ref":"#/components/schemas/History"}}}},"400":{"$ref":"#/components/responses/BadParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/communities":{"get":{"tags":["Communities"],"summary":"Communities, ranked","description":"The groups running several servers, found by the website in their servers' names or set up by their owners,\nranked by real players over 7 days. Matchmaking platforms are listed apart with `platforms=true`.","operationId":"GET_v1_communities","parameters":[{"name":"q","in":"query","description":"Part of its name or website","required":false,"schema":{"type":"string"},"style":"form"},{"name":"platforms","in":"query","description":"List matchmaking platforms instead","required":false,"schema":{"type":"boolean"},"style":"form"},{"$ref":"#/components/parameters/game"},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"A page of communities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityPage"}}}},"400":{"$ref":"#/components/responses/BadParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/communities/{slug}":{"get":{"tags":["Communities"],"summary":"A community and its servers","description":"A community with its description, links and servers.","operationId":"GET_v1_communities_slug","parameters":[{"name":"slug","in":"path","description":"Its slug, often its website: cybershoke.net","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"description":"The community","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityDetailData"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/leaderboards/{game}":{"get":{"tags":["Games"],"summary":"A game's top servers","description":"A game's top servers by average real players over the last 7 days, offline hours counting as empty. Fakes\naren't ranked.","operationId":"GET_v1_leaderboards_game","parameters":[{"name":"game","in":"path","description":"Its slug or Steam app id","required":true,"schema":{"type":"string"},"style":"simple"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"The top servers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Leaderboard"}}}},"400":{"$ref":"#/components/responses/BadParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"bearer":[]}],"deprecated":false}},"/v1/quickplay":{"get":{"tags":["Servers"],"summary":"The server to join now","description":"The one server to join now, as the site's Play now buttons pick it: a free slot and no password, real\nplayers before empty servers, nearest first with `near`, then the busiest. Join with its connect_url.","operationId":"GET_v1_quickplay","parameters":[{"name":"game","in":"query","description":"A game's slug from /v1/games, or its Steam app id","required":true,"schema":{"type":"string"},"style":"form"},{"$ref":"#/components/parameters/mode"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/near"}],"responses":{"200":{"description":"The server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerData"}}}},"400":{"$ref":"#/components/responses/BadParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"security":[{"bearer":[]}],"deprecated":false}}},"components":{"schemas":{"Problem":{"type":"object","required":["title","status","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string","description":"What went wrong, written to be shown to people"},"parameter":{"type":"string","description":"The parameter at fault, when there is one"}}},"PageMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}},"PageLinks":{"type":"object","properties":{"self":{"type":"string"},"first":{"type":"string"},"last":{"type":"string"},"prev":{"type":"string"},"next":{"type":"string"}}},"GameRef":{"type":"object","required":["app_id","slug","name"],"properties":{"app_id":{"type":"integer","examples":[730]},"slug":{"type":"string","examples":["counter-strike-2"]},"name":{"type":"string","examples":["Counter-Strike 2"]}}},"Server":{"type":"object","required":["address","name","game","players","max_players","online","status","connect_url"],"properties":{"address":{"type":"string","description":"ip:port","examples":["163.182.12.174:27015"]},"name":{"type":["string","null"]},"game":{"$ref":"#/components/schemas/GameRef"},"map":{"type":["string","null"]},"mode":{"type":["string","null"],"enum":["bomb-defusal","hostage-rescue","arena","surf","climb","zombies","jailbreak","deathrun","terror-town","roleplay","scp-breach","sandbox","capture-the-flag","control-points","payload","king-of-the-hill","mge-duels","territory","idle","trade","slender","campaign","objective","warcraft-3",null],"description":"Its game mode"},"players":{"type":"integer","description":"Real players now; bots are counted apart"},"bots":{"type":"integer"},"max_players":{"type":"integer"},"online":{"type":"boolean"},"status":{"type":"string","enum":["listed","pending","flagged"],"description":"listed: checked and real. flagged: its numbers look fake, see flagged_reasons"},"country":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string","enum":["free_vip","vip","public","classic","deathmatch","respawn","mix","5v5","retakes","gungame","hns","awp","knife","dust2_only","levels","skins","high_fps","adults"]},"description":"What it offers, read from its name"},"language":{"type":["string","null"],"description":"The language its name says it's in"},"password":{"type":"boolean"},"vac":{"type":"boolean"},"connect_url":{"type":"string","description":"steam://connect/ip:port, to join"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"links":{"type":"object","properties":{"self":{"type":"string"},"web":{"type":"string"}}}}},"ServerDetail":{"allOf":[{"$ref":"#/components/schemas/Server"},{"type":"object","properties":{"flagged_reasons":{"type":"array","items":{"type":"string","enum":["impossible_slots","future_version","nameless_players","missing_names","silent_crowd","shared_roster","farm_ip","steam_sees_nobody","frozen_roster","name_pool","flat_crowd"]},"description":"Why it's flagged: `impossible_slots` claims more players or slots than the game allows; `future_version` reports a game version that doesn't exist yet; `nameless_players` claims players, but its player list is empty; `missing_names` claims far more players than it lists by name; `silent_crowd` claims players, but never answers player list queries; `shared_roster` lists the same player names as other servers on its ip at the same time; `farm_ip` runs on an ip where nearly every other server is fake; `steam_sees_nobody` claims a crowd, but steam counts none of its players; `frozen_roster` most of its players have supposedly been connected for over a day without a single map change; `name_pool` lists the same player names as servers on other ips at the same moment, as fake-player plugins do; `flat_crowd` holds the same number of players around the clock while few different people come and go"},"dedicated":{"type":"boolean"},"os":{"type":["string","null"]},"version":{"type":["string","null"]},"non_steam_clients":{"type":"boolean","description":"Runs ReUnion or dproto, so players without Steam can join"},"plugins":{"type":"array","items":{"type":"string","enum":["SourceMod","Metamod","AMX Mod X","HLstatsX","SourceBans","Stripper","War3FT","War3X","War3XP","UWC3","VIP Core","Shop"]}},"location":{"type":"object","properties":{"country":{"type":["string","null"]},"region":{"type":["string","null"]},"city":{"type":["string","null"]}}},"community":{"type":["object","null"],"properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"claimed":{"type":"boolean","description":"Its owner proved control and manages its page"}}}]},"Player":{"type":"object","properties":{"name":{"type":["string","null"]},"score":{"type":["integer","null"]},"seconds_connected":{"type":["integer","null"],"description":"Since joining, or the last map change on GoldSrc games"}}},"HistoryPoint":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"players":{"type":["integer","null"],"description":"Real players then; null when the server didn't answer"}}},"Game":{"allOf":[{"$ref":"#/components/schemas/GameRef"},{"type":"object","properties":{"servers_online":{"type":"integer"},"players_now":{"type":"integer"}}}]},"GameDetail":{"allOf":[{"$ref":"#/components/schemas/Game"},{"type":"object","properties":{"modes":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","enum":["bomb-defusal","hostage-rescue","arena","surf","climb","zombies","jailbreak","deathrun","terror-town","roleplay","scp-breach","sandbox","capture-the-flag","control-points","payload","king-of-the-hill","mge-duels","territory","idle","trade","slender","campaign","objective","warcraft-3"]},"name":{"type":"string"},"servers_online":{"type":"integer"},"players_now":{"type":"integer"}}}},"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"servers_online":{"type":"integer"},"players_now":{"type":"integer"}}}}}}]},"Ranked":{"type":"object","properties":{"rank":{"type":"integer"},"average_players_7d":{"type":"number"},"server":{"$ref":"#/components/schemas/Server"}}},"Community":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","examples":["cybershoke.net"]},"name":{"type":"string"},"domain":{"type":["string","null"]},"claimed":{"type":"boolean"},"platform":{"type":"boolean","description":"A matchmaking platform (a server per match), not ranked"},"rank":{"type":["integer","null"]},"players_now":{"type":"integer"},"average_players_7d":{"type":["number","null"]},"servers":{"type":"integer"},"servers_online":{"type":"integer"},"flagged_servers":{"type":"integer","description":"Fake servers using its name, not counted"},"games":{"type":"array","items":{"$ref":"#/components/schemas/GameRef"}},"countries":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"self":{"type":"string"},"web":{"type":"string"}}}}},"CommunityDetail":{"allOf":[{"$ref":"#/components/schemas/Community"},{"type":"object","properties":{"description":{"type":["string","null"]},"discord_invite":{"type":["string","null"]},"website_url":{"type":["string","null"]},"member_servers":{"type":"array","items":{"$ref":"#/components/schemas/Server"}}}}]},"ServerPage":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Server"}},"meta":{"$ref":"#/components/schemas/PageMeta"},"links":{"$ref":"#/components/schemas/PageLinks"}}},"CommunityPage":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Community"}},"meta":{"$ref":"#/components/schemas/PageMeta"},"links":{"$ref":"#/components/schemas/PageLinks"}}},"ServerData":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Server"},"meta":{"type":"object"}}},"ServerDetailData":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ServerDetail"},"meta":{"type":"object"}}},"PlayerList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Player"}},"meta":{"type":"object"}}},"Rules":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":{"type":"string"}},"meta":{"type":"object"}}},"History":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HistoryPoint"}},"meta":{"type":"object"}}},"GameList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Game"}},"meta":{"type":"object"}}},"GameDetailData":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/GameDetail"},"meta":{"type":"object"}}},"Leaderboard":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ranked"}},"meta":{"type":"object"}}},"CommunityDetailData":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CommunityDetail"},"meta":{"type":"object"}}}},"responses":{"BadParameter":{"description":"A parameter isn't valid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"No API key, or one that isn't valid or was revoked","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Nothing there","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"Over a rate limit (60 a minute, 10000 a day per key); see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unavailable":{"description":"History or rankings are briefly unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":{"game":{"name":"game","in":"query","required":false,"schema":{"type":"string","examples":["counter-strike-2","730"]},"description":"A game's slug from /v1/games, or its Steam app id"},"mode":{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["bomb-defusal","hostage-rescue","arena","surf","climb","zombies","jailbreak","deathrun","terror-town","roleplay","scp-breach","sandbox","capture-the-flag","control-points","payload","king-of-the-hill","mge-duels","territory","idle","trade","slender","campaign","objective","warcraft-3"]},"description":"The game mode, read from the map name (or the plugin, for Warcraft 3)"},"country":{"name":"country","in":"query","required":false,"schema":{"type":"string","examples":["DE"]},"description":"The server's country, ISO 3166-1 alpha-2"},"tag":{"name":"tag[]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["free_vip","vip","public","classic","deathmatch","respawn","mix","5v5","retakes","gungame","hns","awp","knife","dust2_only","levels","skins","high_fps","adults"]}},"description":"What it offers, read from its name; all must match"},"lang":{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["bg","cs","de","en","es","fr","hu","it","pl","pt","ro","ru","tr","uk"]},"description":"The language its name says it's in ([RU], [PL]…)"},"near":{"name":"near","in":"query","required":false,"schema":{"type":"string","examples":["52.52,13.40"]},"description":"The player's location, latitude,longitude, for nearest first"},"page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"The page, from 1"},"per_page":{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"How many on a page"},"address":{"name":"address","in":"path","required":true,"schema":{"type":"string","examples":["163.182.12.174:27015"]},"description":"The server's address, ip:port"}},"requestBodies":{},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your API key from https://lobbyverse.com/account/api-keys, as `Authorization: Bearer lv_…`"}},"headers":{},"examples":{},"links":{},"callbacks":{}},"security":[{"bearer":[]}],"tags":[{"name":"Servers"},{"name":"Games"},{"name":"Communities"}]}