{"openapi":"3.1.0","info":{"title":"Minecraft API","description":"A versatile minecraft api for querying player information in both Java and Bedrock editions. Retrieve details such as player names, uuids, xuids (Bedrock), profiles (skins), and server information for both Java and Bedrock platforms. Enhance your gaming applications with seamless access to comprehensive player data.","contact":{"url":"https://github.com/iwmedia","email":"contact@mc-api.io"},"version":"4.10.2"},"servers":[{"url":"/","description":"default"}],"tags":[{"name":"Profile","description":"Get profile information for a player by their uuid, xuid or name."},{"name":"Render","description":"Render a player's skin by their uuid, xuid or name. A player without a usable skin is served the fallback render of the requested type, so these endpoints always answer with an image."},{"name":"Name","description":"Get the name of a player by their uuid or xuid."},{"name":"UUID","description":"Get the uuid of a player by their name."},{"name":"Favicon","description":"Get the favicon of a Java Minecraft server."},{"name":"Server","description":"Get information about a server by host and port."}],"paths":{"/uuid/{name}":{"get":{"tags":["UUID"],"summary":"Get the uuid of a Java player by their name.","operationId":"getUuidByName","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the uuid of the given player, including the xuid for bedrock players.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UUIDDocument"}}}},"400":{"description":"Returns if the given name cannot belong to that edition."},"404":{"description":"Returns if no player was found for the given input."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if an upstream service is currently unavailable."}}}},"/uuid/{name}/{edition}":{"get":{"tags":["UUID"],"summary":"Get the uuid of a player by their name and edition.","operationId":"getUuidByNameAndEdition","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"edition","in":"path","required":true,"schema":{"type":"string","enum":["JAVA","BEDROCK"]}}],"responses":{"200":{"description":"Returns the uuid of the given player, including the xuid for bedrock players.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UUIDDocument"}}}},"400":{"description":"Returns if the given name cannot belong to that edition."},"404":{"description":"Returns if no player was found for the given input."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if an upstream service is currently unavailable."}}}},"/server/{edition}/{host}":{"get":{"tags":["Server"],"summary":"Get the status of a server by its host, deriving the port.","operationId":"getServerByHost","parameters":[{"name":"edition","in":"path","required":true,"schema":{"type":"string","enum":["JAVA","BEDROCK"]}},{"name":"host","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the server information of the given address. A server that does not answer is reported as offline, not as an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerDocument"}}}},"400":{"description":"Returns if the given edition is unknown, the given host is not a valid hostname or ip address, or the given port is outside the valid range."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if the server could not be pinged at all."}}}},"/server/{edition}/{host}/{port}":{"get":{"tags":["Server"],"summary":"Get the status of a server by its host and port.","operationId":"getServerByHostAndPort","parameters":[{"name":"edition","in":"path","required":true,"schema":{"type":"string","enum":["JAVA","BEDROCK"]}},{"name":"host","in":"path","required":true,"schema":{"type":"string"}},{"name":"port","in":"path","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Returns the server information of the given address. A server that does not answer is reported as offline, not as an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerDocument"}}}},"400":{"description":"Returns if the given edition is unknown, the given host is not a valid hostname or ip address, or the given port is outside the valid range."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if the server could not be pinged at all."}}}},"/render/{xuid}":{"get":{"tags":["Render"],"summary":"Render a bedrock player's face by their xuid.","operationId":"renderByXuid","parameters":[{"name":"xuid","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"size","in":"query","description":"Size of the rendered image in pixels. Values outside the supported range are clamped.","required":false,"schema":{"type":"integer","format":"int32","default":256,"maximum":1024,"minimum":8}}],"responses":{"200":{"description":"Returns the rendered skin of the given player.","headers":{"Cache-Control":{"description":"Cache-Control header whose max-age matches the remaining server-side cache lifetime.","style":"simple"}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Returns if the given render type or size is unknown."},"500":{"description":"Returns if an internal server error occurred."}}}},"/render/{uuid}":{"get":{"tags":["Render"],"summary":"Render a player's face by their uuid.","operationId":"renderByUuid","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"size","in":"query","description":"Size of the rendered image in pixels. Values outside the supported range are clamped.","required":false,"schema":{"type":"integer","format":"int32","default":256,"maximum":1024,"minimum":8}}],"responses":{"200":{"description":"Returns the rendered skin of the given player.","headers":{"Cache-Control":{"description":"Cache-Control header whose max-age matches the remaining server-side cache lifetime.","style":"simple"}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Returns if the given render type or size is unknown."},"500":{"description":"Returns if an internal server error occurred."}}}},"/render/{type}/{xuid}":{"get":{"tags":["Render"],"summary":"Render a bedrock player's skin by their xuid.","operationId":"renderTypeByXuid","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["FACE","HEAD","BUST","FULL"]}},{"name":"xuid","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"size","in":"query","description":"Size of the rendered image in pixels. Values outside the supported range are clamped.","required":false,"schema":{"type":"integer","format":"int32","default":256,"maximum":1024,"minimum":8}}],"responses":{"200":{"description":"Returns the rendered skin of the given player.","headers":{"Cache-Control":{"description":"Cache-Control header whose max-age matches the remaining server-side cache lifetime.","style":"simple"}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Returns if the given render type or size is unknown."},"500":{"description":"Returns if an internal server error occurred."}}}},"/render/{type}/{uuid}":{"get":{"tags":["Render"],"summary":"Render a player's skin by their uuid.","operationId":"renderTypeByUuid","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["FACE","HEAD","BUST","FULL"]}},{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"size","in":"query","description":"Size of the rendered image in pixels. Values outside the supported range are clamped.","required":false,"schema":{"type":"integer","format":"int32","default":256,"maximum":1024,"minimum":8}}],"responses":{"200":{"description":"Returns the rendered skin of the given player.","headers":{"Cache-Control":{"description":"Cache-Control header whose max-age matches the remaining server-side cache lifetime.","style":"simple"}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Returns if the given render type or size is unknown."},"500":{"description":"Returns if an internal server error occurred."}}}},"/render/{type}/{name}/{edition}":{"get":{"tags":["Render"],"summary":"Render a player's skin by their name and edition.","operationId":"renderTypeByNameAndEdition","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["FACE","HEAD","BUST","FULL"]}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"edition","in":"path","required":true,"schema":{"type":"string","enum":["JAVA","BEDROCK"]}},{"name":"size","in":"query","description":"Size of the rendered image in pixels. Values outside the supported range are clamped.","required":false,"schema":{"type":"integer","format":"int32","default":256,"maximum":1024,"minimum":8}}],"responses":{"200":{"description":"Returns the rendered skin of the given player.","headers":{"Cache-Control":{"description":"Cache-Control header whose max-age matches the remaining server-side cache lifetime.","style":"simple"}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Returns if the given render type or size is unknown."},"500":{"description":"Returns if an internal server error occurred."}}}},"/profile/{xuid}":{"get":{"tags":["Profile"],"summary":"Get the profile of a bedrock player by their xuid.","operationId":"getProfileByXuid","parameters":[{"name":"xuid","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Returns the profile (including skin) of the player.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileDocument"}}}},"404":{"description":"Returns if no player was found for the given input."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if an upstream service is currently unavailable."}}}},"/profile/{uuid}":{"get":{"tags":["Profile"],"summary":"Get the profile of a player by their uuid.","operationId":"getProfileByUuid","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Returns the profile (including skin) of the player.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileDocument"}}}},"404":{"description":"Returns if no player was found for the given input."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if an upstream service is currently unavailable."}}}},"/profile/{name}/{edition}":{"get":{"tags":["Profile"],"summary":"Get the profile of a player by their name and edition.","operationId":"getProfileByNameAndEdition","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"edition","in":"path","required":true,"schema":{"type":"string","enum":["JAVA","BEDROCK"]}}],"responses":{"200":{"description":"Returns the profile (including skin) of the player.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileDocument"}}}},"404":{"description":"Returns if no player was found for the given input."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if an upstream service is currently unavailable."},"400":{"description":"Returns if the given edition is unknown or the given name cannot belong to that edition."}}}},"/name/{xuid}":{"get":{"tags":["Name"],"summary":"Get the name of a bedrock player by their xuid.","operationId":"getNameByXuid","parameters":[{"name":"xuid","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Returns the name of the player.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameDocument"}}}},"404":{"description":"Returns if no player was found for the given input."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if an upstream service is currently unavailable."}}}},"/name/{uuid}":{"get":{"tags":["Name"],"summary":"Get the name of a player by their uuid.","operationId":"getNameByUuid","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Returns the name of the player.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NameDocument"}}}},"404":{"description":"Returns if no player was found for the given input."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if an upstream service is currently unavailable."}}}},"/favicon/{host}":{"get":{"tags":["Favicon"],"summary":"Get the favicon of a server by its host, deriving the port.","operationId":"getFaviconByHost","parameters":[{"name":"host","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the favicon of the server.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Returns if the server has no usable favicon."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if the server could not be pinged at all."},"400":{"description":"Returns if the given host is not a valid hostname or ip address."}}}},"/favicon/{host}/{port}":{"get":{"tags":["Favicon"],"summary":"Get the favicon of a server by its host and port.","operationId":"getFaviconByHostAndPort","parameters":[{"name":"host","in":"path","required":true,"schema":{"type":"string"}},{"name":"port","in":"path","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Returns the favicon of the server.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Returns if the server has no usable favicon."},"500":{"description":"Returns if an internal server error occurred."},"502":{"description":"Returns if an upstream service answered with something unusable."},"503":{"description":"Returns if the server could not be pinged at all."},"400":{"description":"Returns if the given host is not a valid hostname or ip address, or the given port is outside the valid range."}}}}},"components":{"schemas":{"UUIDDocument":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"The UUID of the player","example":"bef1d0a8-e281-4f69-9200-64e07c235c96"},"xuid":{"type":"integer","format":"int64","description":"The XUID of the player.","example":2535439361006376},"cachedAt":{"type":"integer","format":"int64","description":"The timestamp when the document was cached.","example":1704063600000}}},"ServerDocument":{"type":"object","properties":{"online":{"type":"boolean","description":"Whether the server is online or not.","example":true},"hostname":{"type":"string","description":"The hostname of the server.","example":"hypixel.net"},"address":{"type":"string","description":"The address of the server.","example":"mc.hypixel.net"},"port":{"type":"integer","format":"int32","description":"The port of the server.","example":25565},"ping":{"type":"integer","format":"int64","description":"The ping of the server in milliseconds.","example":100},"motd":{"type":"string","description":"The MOTD of the server.","example":"A Minecraft Server"},"rawMotd":{"type":"string","description":"The raw MOTD of the server.","example":"§aMinecraft §7Server"},"version":{"type":"string","description":"The version of the server.","example":"1.20.1"},"protocol":{"type":"integer","format":"int32","description":"The protocol of the server.","example":754},"onlinePlayers":{"type":"integer","format":"int32","description":"The amount of online players on the server.","example":100},"maxPlayers":{"type":"integer","format":"int32","description":"The maximum amount of players on the server.","example":1000},"players":{"type":"array","description":"The list of online players on the server.","example":["ByteException_","Notch"],"items":{"type":"string"}},"favicon":{"type":"string","description":"The favicon of the server.","example":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8..."},"cachedAt":{"type":"integer","format":"int64","description":"The timestamp when the server document was cached.","example":1704063600000}}},"ProfileDocument":{"type":"object","properties":{"name":{"type":"string","description":"The name of the player.","example":"ByteException_"},"uuid":{"type":"string","format":"uuid","description":"The UUID of the player.","example":"bef1d0a8-e281-4f69-9200-64e07c235c96"},"xuid":{"type":"integer","format":"int64","description":"The XUID of the player.","example":2535439361006376},"textures":{"type":"object","additionalProperties":{"type":"string"},"description":"The textures of the player.","example":{"signature":"...","value":"..."}},"decodedTexture":{"type":"object","additionalProperties":{},"description":"The decoded textures of the player, without the timestamp the session server stamps them with.","example":{"profileId":"bef1d0a8e2814f69920064e07c235c96","profileName":"ByteException_","textures":{"SKIN":{"url":"https://textures.minecraft.net/texture/..."},"CAPE":{"url":"https://textures.minecraft.net/texture/..."}}}},"names":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"A map of all names the player has used","example":{"ByteException_":1704063600000}},"cachedAt":{"type":"integer","format":"int64","description":"The timestamp when the document was cached.","example":1704063600000}}},"NameDocument":{"type":"object","properties":{"name":{"type":"string","description":"The name of the player","example":"ByteException_"},"uuid":{"type":"string","format":"uuid","description":"The UUID of the player","example":"bef1d0a8-e281-4f69-9200-64e07c235c96"},"cachedAt":{"type":"integer","format":"int64","description":"The timestamp when the document was cached.","example":1704063600000}}}}}}