{"openapi":"3.1.0","info":{"title":"HypnosMP API","description":"Public API for HypnosMP player stats, leaderboards, and lookups.\n\nAuthenticate with the `X-API-Key` header on protected endpoints. `/v1/stats` requires no key.","license":{"name":"MIT","identifier":"MIT"},"version":"1.0.0"},"servers":[{"url":"/"}],"paths":{"/v1/leaderboard/{stat}/{page}":{"get":{"tags":["Leaderboard"],"operationId":"leaderboard_inner","parameters":[{"name":"stat","in":"path","description":"kills | deaths | money | orbs | playtime","required":true,"schema":{"type":"string"}},{"name":"page","in":"path","description":"Page number (default 1)","required":true,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeaderboardResponse"}}}}},"security":[{"api_key":[]}]}},"/v1/lookup/name/{playername}":{"get":{"tags":["Lookup"],"operationId":"by_name","parameters":[{"name":"playername","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerLookup"}}}}},"security":[{"api_key":[]}]}},"/v1/lookup/uuid/{playeruuid}":{"get":{"tags":["Lookup"],"operationId":"by_uuid","parameters":[{"name":"playeruuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerLookup"}}}}},"security":[{"api_key":[]}]}},"/v1/player/{id}/stats":{"get":{"tags":["Player"],"operationId":"full_stats","parameters":[{"name":"id","in":"path","description":"Player UUID or username","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full player stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullPlayerStats"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Player not found"}},"security":[{"api_key":[]}]}},"/v1/player/{id}/stats/balances":{"get":{"tags":["Player"],"operationId":"balances","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"api_key":[]}]}},"/v1/player/{id}/stats/balances/money":{"get":{"tags":["Player"],"operationId":"money","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"api_key":[]}]}},"/v1/player/{id}/stats/balances/orbs":{"get":{"tags":["Player"],"operationId":"orbs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"api_key":[]}]}},"/v1/player/{id}/stats/deaths":{"get":{"tags":["Player"],"operationId":"deaths","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeathsResponse"}}}}},"security":[{"api_key":[]}]}},"/v1/player/{id}/stats/kills":{"get":{"tags":["Player"],"operationId":"kills","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KillsResponse"}}}}},"security":[{"api_key":[]}]}},"/v1/player/{id}/stats/playtime":{"get":{"tags":["Player"],"operationId":"playtime","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaytimeResponse"}}}}},"security":[{"api_key":[]}]}},"/v1/stats":{"get":{"tags":["Meta"],"summary":"No rate limit applied (per spec).","operationId":"api_stats","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStatsResponse"}}}}}}}},"components":{"schemas":{"ApiStatsResponse":{"type":"object","required":["name","version","uptime_secs","default_rate_limit_per_minute","cache_ttl_secs","active_api_keys","redis_enabled"],"properties":{"active_api_keys":{"type":"integer","format":"int64"},"cache_ttl_secs":{"type":"integer","format":"int64","minimum":0},"default_rate_limit_per_minute":{"type":"integer","format":"int32","minimum":0},"name":{"type":"string"},"redis_enabled":{"type":"boolean"},"uptime_secs":{"type":"integer","format":"int64","minimum":0},"version":{"type":"string"}}},"Balances":{"type":"object","required":["money","orbs"],"properties":{"money":{"type":"string"},"orbs":{"type":"string"}}},"DeathsResponse":{"type":"object","required":["deaths"],"properties":{"deaths":{"type":"integer","format":"int64"}}},"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"details":{},"message":{"type":"string"},"request_id":{"type":"string"}}},"FullPlayerStats":{"type":"object","required":["uuid","username","kills","deaths","playtime_ticks","balances"],"properties":{"balances":{"$ref":"#/components/schemas/Balances"},"deaths":{"type":"integer","format":"int64"},"kills":{"type":"integer","format":"int64"},"playtime_ticks":{"type":"integer","format":"int64"},"username":{"type":"string"},"uuid":{"type":"string"}}},"KillsResponse":{"type":"object","required":["kills"],"properties":{"kills":{"type":"integer","format":"int64"}}},"LeaderboardResponse":{"type":"object","required":["stat","page","per_page","total_pages","results"],"properties":{"page":{"type":"integer","format":"int32","minimum":0},"per_page":{"type":"integer","format":"int32","minimum":0},"results":{"type":"array","items":{"$ref":"#/components/schemas/LeaderboardRow"}},"stat":{"type":"string"},"total_pages":{"type":"integer","format":"int32","minimum":0}}},"LeaderboardRow":{"type":"object","required":["rank","uuid","username","value"],"properties":{"rank":{"type":"integer","format":"int32","minimum":0},"username":{"type":"string"},"uuid":{"type":"string"},"value":{}}},"PlayerLookup":{"type":"object","required":["username","uuid","rank"],"properties":{"rank":{"type":"string"},"username":{"type":"string"},"uuid":{"type":"string"}}},"PlaytimeResponse":{"type":"object","required":["playtime_ticks"],"properties":{"playtime_ticks":{"type":"integer","format":"int64"}}},"VanillaStats":{"type":"object","required":["kills","deaths","playtime_ticks"],"properties":{"deaths":{"type":"integer","format":"int64"},"kills":{"type":"integer","format":"int64"},"playtime_ticks":{"type":"integer","format":"int64"}}}},"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Player","description":"Player statistics"},{"name":"Leaderboard","description":"Highest → lowest rankings"},{"name":"Lookup","description":"Username / UUID / rank"},{"name":"Meta","description":"API metadata"}]}