{"openapi":"3.1.0","info":{"title":"Bedlify Public API","version":"5.0.0","summary":"Observations from Hypixel lobbies: names, skins, latency, locations, chat, Lunar cosmetics and rank gifts.","termsOfService":"/tos","description":"## Introduction\n\nA fleet of bots stands in Hypixel lobbies around the clock and writes down what is publicly\nvisible there. This API hands that record back.\n\nEverything here is what any player standing in the same lobby could also see: names and their\nhistory, skins, the latency the tab list shows, which lobby somebody was in and when, public\nchat messages, visible Lunar cosmetics, and the rank gifts Hypixel announces in chat.\n\nThere is no key and no sign-up. Point a request at an endpoint and read the answer.\n\n## Limits\n\nRequests are counted per client address: 300 per 5 minutes.\nIPv6 is counted per /64 rather than per address, so a prefix counts as one client.\n\nEvery response carries headers to help you stay under it:\n\n- `X-RateLimit-Limit` - requests allowed per window.\n- `X-RateLimit-Remaining` - what is left in the current window.\n- `X-RateLimit-Reset` - the Unix second at which the window resets.\n\nGoing over gives you `429` with a `Retry-After` header. The window is fixed rather than\nsliding, so that number is exact rather than an estimate.\n\nEvery timestamp in a response is Unix seconds in UTC.\n\n## Rules\n\nThe API is free to use in most applications, but a few things will get an address blocked:\n\n- Do not use the data to harass, dox or target individual players.\n- If you use this commercially, credit it visibly.\n- Do not spread requests across several addresses to get around the limit.\n- Cache what you can. Asking for the same record in a loop helps nobody.\n\nUsing the API means you accept the [terms of service](/tos)."},"servers":[{"url":"https://api.bedlify.xyz","description":"This server"}],"tags":[{"name":"Players","description":"Seven views on what has been observed about one player. Each one answers with the UUID, when the player was first and last seen at all, and the section you asked for."}],"components":{"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Stable code to branch on in your own code.","example":"unknown_player"},"message":{"type":"string","description":"Explanation for humans."},"documentation":{"type":"string","description":"Pointer back to these docs when the path was unknown."}},"example":{"error":"invalid_uuid","message":"Expected a UUID v4, with or without dashes."}},"NameEntry":{"type":"object","required":["name","timestamp"],"properties":{"name":{"type":"string","example":"Technoblade"},"timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948}}},"SkinEntry":{"type":"object","required":["url","timestamp"],"properties":{"url":{"type":"string","format":"uri","description":"Texture URL on textures.minecraft.net."},"model":{"type":["string","null"],"enum":["slim","classic",null],"description":"Arm model, when the server reported one."},"timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948}}},"PingEntry":{"type":"object","required":["ping","timestamp"],"properties":{"ping":{"type":["integer","null"],"description":"Latency in milliseconds, as shown in the tab list.","example":42},"timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948}}},"Sighting":{"type":"object","required":["gametype","timestamp"],"description":"One place the player was seen. mode, map and lobbyname are absent when Hypixel did not report them.","properties":{"gametype":{"type":"string","example":"BEDWARS"},"mode":{"type":"string","example":"BEDWARS_EIGHT_TWO"},"map":{"type":"string","example":"Amazon"},"lobbyname":{"type":"string","example":"bedwarslobby3"},"timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948}}},"ChatEntry":{"type":"object","required":["message","timestamp"],"properties":{"message":{"type":"string","description":"Public lobby message, with formatting codes stripped."},"mode":{"type":["string","null"],"description":"Game mode of the lobby at the time."},"timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948}}},"MentionEntry":{"type":"object","required":["message","timestamp","from"],"description":"Somebody else's message that names this player.","properties":{"message":{"type":"string"},"mode":{"type":["string","null"]},"timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948},"from":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name of the sender."},"uuid":{"type":["string","null"],"format":"uuid","description":"UUID of the sender, when known."}}}}},"Cosmetic":{"type":"object","required":["id","firstSeen","lastSeen"],"properties":{"id":{"type":"integer","description":"Lunar cosmetic id."},"firstSeen":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948},"lastSeen":{"type":"integer","format":"int64","description":"Unix timestamp in seconds.","example":1788594948}}},"Lunar":{"type":"object","description":"Lunar Client presence. firstSeen is null when the player has never been seen on Lunar.","properties":{"firstSeen":{"type":["integer","null"],"format":"int64"},"lastSeen":{"type":["integer","null"],"format":"int64"},"cosmetics":{"type":"array","items":{"$ref":"#/components/schemas/Cosmetic"}}}}}},"paths":{"/ping/{uuid}":{"get":{"operationId":"getPing","summary":"Latency","description":"The latency shown in the tab list, sampled while a bot shared a lobby with the player.","tags":["Players"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"description":"The player UUID v4, with or without dashes."}],"responses":{"200":{"description":"Latency","content":{"application/json":{"schema":{"type":"object","required":["uuid","ping"],"properties":{"uuid":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"firstSeen":{"type":"integer","format":"int64","description":"When this player was first observed at all."},"lastSeen":{"type":"integer","format":"int64","description":"When this player was last observed at all."},"ping":{"type":"array","items":{"$ref":"#/components/schemas/PingEntry"}}}}}}},"400":{"description":"The UUID is not a valid UUID v4.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing is stored for this UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The address hit its rate limit. Retry-After gives the wait in seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/played/{uuid}":{"get":{"operationId":"getPlayed","summary":"Where the player was seen","description":"Every lobby the player was observed in, with the game type and the time.","tags":["Players"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"description":"The player UUID v4, with or without dashes."}],"responses":{"200":{"description":"Where the player was seen","content":{"application/json":{"schema":{"type":"object","required":["uuid","played"],"properties":{"uuid":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"firstSeen":{"type":"integer","format":"int64","description":"When this player was first observed at all."},"lastSeen":{"type":"integer","format":"int64","description":"When this player was last observed at all."},"played":{"type":"array","items":{"$ref":"#/components/schemas/Sighting"}}}}}}},"400":{"description":"The UUID is not a valid UUID v4.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing is stored for this UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The address hit its rate limit. Retry-After gives the wait in seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/namehistory/{uuid}":{"get":{"operationId":"getNamehistory","summary":"Name history","description":"Every name the player has been seen under, oldest first.","tags":["Players"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"description":"The player UUID v4, with or without dashes."}],"responses":{"200":{"description":"Name history","content":{"application/json":{"schema":{"type":"object","required":["uuid","namehistory"],"properties":{"uuid":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"firstSeen":{"type":"integer","format":"int64","description":"When this player was first observed at all."},"lastSeen":{"type":"integer","format":"int64","description":"When this player was last observed at all."},"namehistory":{"type":"array","items":{"$ref":"#/components/schemas/NameEntry"}}}}}}},"400":{"description":"The UUID is not a valid UUID v4.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing is stored for this UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The address hit its rate limit. Retry-After gives the wait in seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/skinhistory/{uuid}":{"get":{"operationId":"getSkinhistory","summary":"Skin history","description":"Every skin texture the player has been seen wearing, oldest first.","tags":["Players"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"description":"The player UUID v4, with or without dashes."}],"responses":{"200":{"description":"Skin history","content":{"application/json":{"schema":{"type":"object","required":["uuid","skinhistory"],"properties":{"uuid":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"firstSeen":{"type":"integer","format":"int64","description":"When this player was first observed at all."},"lastSeen":{"type":"integer","format":"int64","description":"When this player was last observed at all."},"skinhistory":{"type":"array","items":{"$ref":"#/components/schemas/SkinEntry"}}}}}}},"400":{"description":"The UUID is not a valid UUID v4.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing is stored for this UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The address hit its rate limit. Retry-After gives the wait in seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lunar/{uuid}":{"get":{"operationId":"getLunar","summary":"Lunar Client","description":"Whether the player has been seen on Lunar Client, and which cosmetics were visible.","tags":["Players"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"description":"The player UUID v4, with or without dashes."}],"responses":{"200":{"description":"Lunar Client","content":{"application/json":{"schema":{"type":"object","required":["uuid","lunar"],"properties":{"uuid":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"firstSeen":{"type":"integer","format":"int64","description":"When this player was first observed at all."},"lastSeen":{"type":"integer","format":"int64","description":"When this player was last observed at all."},"lunar":{"$ref":"#/components/schemas/Lunar"}}}}}},"400":{"description":"The UUID is not a valid UUID v4.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing is stored for this UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The address hit its rate limit. Retry-After gives the wait in seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mentions/{uuid}":{"get":{"operationId":"getMentions","summary":"Mentions","description":"Public messages from other players that name this player.","tags":["Players"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"description":"The player UUID v4, with or without dashes."}],"responses":{"200":{"description":"Mentions","content":{"application/json":{"schema":{"type":"object","required":["uuid","mentions"],"properties":{"uuid":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"firstSeen":{"type":"integer","format":"int64","description":"When this player was first observed at all."},"lastSeen":{"type":"integer","format":"int64","description":"When this player was last observed at all."},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/MentionEntry"}}}}}}},"400":{"description":"The UUID is not a valid UUID v4.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing is stored for this UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The address hit its rate limit. Retry-After gives the wait in seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chat/{uuid}":{"get":{"operationId":"getChat","summary":"Chat","description":"Public lobby messages sent by this player.","tags":["Players"],"parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"description":"The player UUID v4, with or without dashes."}],"responses":{"200":{"description":"Chat","content":{"application/json":{"schema":{"type":"object","required":["uuid","chat"],"properties":{"uuid":{"type":"string","format":"uuid","description":"The player UUID v4, with or without dashes.","example":"b69aa6b2-126b-4556-8f87-84266b295a1f"},"firstSeen":{"type":"integer","format":"int64","description":"When this player was first observed at all."},"lastSeen":{"type":"integer","format":"int64","description":"When this player was last observed at all."},"chat":{"type":"array","items":{"$ref":"#/components/schemas/ChatEntry"}}}}}}},"400":{"description":"The UUID is not a valid UUID v4.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing is stored for this UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The address hit its rate limit. Retry-After gives the wait in seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}