OpenAPI 3.1.0v4.12.1

Minecraft API documentation

Every endpoint of the Minecraft API, with its parameters, status codes, response schemas and ready-to-run samples. Generated from the OpenAPI document the API publishes, so it always matches what the service actually does.

Back to the lookup tools

Base URL

Every endpoint is a GET request under one base URL, and CORS is open, so browser code can read from it directly.

Base URL

https://mc-api.io

Editions and identifiers

edition accepts JAVA or BEDROCK, in any casing.
UUIDs work with or without dashes. Bedrock UUIDs are derived from the XUID and start with a long run of zeros.
An xuid is a 64-bit integer and only exists for Bedrock accounts.
Endpoints that take an identifier need no edition - the identifier already implies it.

Caching and limits

JSON documents carry a cachedAt field in epoch milliseconds, telling you when the API last talked to the upstream service. Renders are served with a one day cache header. Cache on your side and reuse the identifiers you already resolved rather than looking the same player up twice.

Error responses

Failures answer with the status code listed on each endpoint and a JSON body in this shape. A 503 means an upstream service is unavailable, not that your request was wrong.

application/json

{  "error": true,  "message": "Could not find uuid from name 'Notchh'. Wrong edition?",  "cause": "ProfileNotFoundException"}

Endpoint reference

Generated from the OpenAPI document the API publishes. Nothing here is written by hand: the document is read when this page is built and read again when you open it, so it cannot drift from the API.

Contents

Profile

Get profile information for a player by their uuid, xuid or name.

GET/profile/{uuid or xuid}

Get the profile of a player by their uuid.

Operation IDgetProfileByUuidgetProfileByXuid

Path parameters

Path parameters of GET /profile/{uuid or xuid}
Name	Type	Required	Example
One path segment, 2 accepted formats - send exactly one:
uuid	stringuuid	One of	`bef1d0a8-e281-4f69-9200-64e07c235c96`
Get the profile of a player by their uuid.
xuid	integerint64	One of	`2535439361006376`
Get the profile of a bedrock player by their xuid.

Responses

Responses of GET /profile/{uuid or xuid}
Status	Body	Description
200	application/jsonProfileDocument	Returns the profile (including skin) of the player.
404		Returns if no player was found for the given input.
500		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if an upstream service is currently unavailable.

Example response

application/json

{  "name": "ByteException_",  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "xuid": 2535439361006376,  "textures": {    "signature": "...",    "value": "..."  },  "decodedTexture": {    "profileId": "bef1d0a8e2814f69920064e07c235c96",    "profileName": "ByteException_",    "textures": {      "SKIN": {        "url": "https://textures.minecraft.net/texture/..."      },      "CAPE": {        "url": "https://textures.minecraft.net/texture/..."      }    }  },  "names": {    "ByteException_": 1704063600000  },  "cachedAt": 1704063600000}

Request

curl -s "https://mc-api.io/profile/bef1d0a8-e281-4f69-9200-64e07c235c96"

const response = await fetch("https://mc-api.io/profile/bef1d0a8-e281-4f69-9200-64e07c235c96");
if (!response.ok) {  const { message } = await response.json();  throw new Error(message);}
const profile = await response.json();console.log(profile);

import requests
response = requests.get("https://mc-api.io/profile/bef1d0a8-e281-4f69-9200-64e07c235c96", timeout=10)response.raise_for_status()
profile = response.json()print(profile)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/profile/bef1d0a8-e281-4f69-9200-64e07c235c96")).build();
HttpResponse<String> response = client.sendAsync(request, BodyHandlers.ofString()).join();System.out.println(response.body());

Try this endpoint

uuid or xuid

https://mc-api.io/profile/bef1d0a8-e281-4f69-9200-64e07c235c96

GET/profile/{name}/{edition}

Get the profile of a player by their name and edition.

Operation IDgetProfileByNameAndEdition

Path parameters

Path parameters of GET /profile/{name}/{edition}
Name	Type	Required	Example
name	string	Yes	`ByteException_`
edition	string	Yes	`JAVA`
`JAVABEDROCK`

Responses

Responses of GET /profile/{name}/{edition}
Status	Body	Description
200	application/jsonProfileDocument	Returns the profile (including skin) of the player.
400		Returns if the given edition is unknown or the given name cannot belong to that edition.
404		Returns if no player was found for the given input.
500		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if an upstream service is currently unavailable.

Example response

application/json

{  "name": "ByteException_",  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "xuid": 2535439361006376,  "textures": {    "signature": "...",    "value": "..."  },  "decodedTexture": {    "profileId": "bef1d0a8e2814f69920064e07c235c96",    "profileName": "ByteException_",    "textures": {      "SKIN": {        "url": "https://textures.minecraft.net/texture/..."      },      "CAPE": {        "url": "https://textures.minecraft.net/texture/..."      }    }  },  "names": {    "ByteException_": 1704063600000  },  "cachedAt": 1704063600000}

Request

curl -s "https://mc-api.io/profile/ByteException_/JAVA"

const response = await fetch("https://mc-api.io/profile/ByteException_/JAVA");
if (!response.ok) {  const { message } = await response.json();  throw new Error(message);}
const profile = await response.json();console.log(profile);

import requests
response = requests.get("https://mc-api.io/profile/ByteException_/JAVA", timeout=10)response.raise_for_status()
profile = response.json()print(profile)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/profile/ByteException_/JAVA")).build();
HttpResponse<String> response = client.sendAsync(request, BodyHandlers.ofString()).join();System.out.println(response.body());

Try this endpoint

name

edition

https://mc-api.io/profile/ByteException_/JAVA

Render

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.

GET/render/{uuid or xuid}

Render a player's face by their uuid.

Operation IDrenderByUuidrenderByXuid

Path parameters

Path parameters of GET /render/{uuid or xuid}
Name	Type	Required	Example
One path segment, 2 accepted formats - send exactly one:
uuid	stringuuid	One of	`bef1d0a8-e281-4f69-9200-64e07c235c96`
Render a player's face by their uuid.
xuid	integerint64	One of	`2535439361006376`
Render a bedrock player's face by their xuid.

Query parameters

Query parameters of GET /render/{uuid or xuid}
Name	Type	Required	Example
size	integerint32	No	`256`
Size of the rendered image in pixels. Values outside the supported range are clamped. Ceilings differ per render type: FACE reaches 1024 px, HEAD and BUST cap at 512 px, and FULL caps at 512 × 832. Range 8 – 1024

Responses

Responses of GET /render/{uuid or xuid}
Status	Body	Description
200	image/png	Returns the rendered skin of the given player.
400		Returns if the given render type or size is unknown.
500		Returns if an internal server error occurred.

Example image

Example response of GET /render/{uuid or xuid}

Responds with image/png. Use the URL directly in an img tag.

Request

curl -s "https://mc-api.io/render/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256" -o render.png

const response = await fetch("https://mc-api.io/render/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256");const blob = await response.blob();
document.querySelector("img").src = URL.createObjectURL(blob);

import requests
response = requests.get("https://mc-api.io/render/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256", timeout=10)response.raise_for_status()
with open("render.png", "wb") as file:    file.write(response.content)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/render/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256")).build();
HttpResponse<Path> response = client    .sendAsync(request, BodyHandlers.ofFile(Path.of("render.png")))    .join();

Try this endpoint

uuid or xuid

size (optional)

https://mc-api.io/render/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256

GET/render/{type}/{uuid or xuid}

Render a player's skin by their uuid.

Operation IDrenderTypeByUuidrenderTypeByXuid

Path parameters

Path parameters of GET /render/{type}/{uuid or xuid}
Name	Type	Required	Example
type	string	Yes	`FACE`
`FACEHEADBUSTFULL`
One path segment, 2 accepted formats - send exactly one:
uuid	stringuuid	One of	`bef1d0a8-e281-4f69-9200-64e07c235c96`
Render a player's skin by their uuid.
xuid	integerint64	One of	`2535439361006376`
Render a bedrock player's skin by their xuid.

Query parameters

Query parameters of GET /render/{type}/{uuid or xuid}
Name	Type	Required	Example
size	integerint32	No	`256`
Size of the rendered image in pixels. Values outside the supported range are clamped. Ceilings differ per render type: FACE reaches 1024 px, HEAD and BUST cap at 512 px, and FULL caps at 512 × 832. Range 8 – 1024

Responses

Responses of GET /render/{type}/{uuid or xuid}
Status	Body	Description
200	image/png	Returns the rendered skin of the given player.
400		Returns if the given render type or size is unknown.
500		Returns if an internal server error occurred.

Example image

Example response of GET /render/{type}/{uuid or xuid}

Responds with image/png. Use the URL directly in an img tag.

Request

curl -s "https://mc-api.io/render/FACE/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256" -o render.png

const response = await fetch("https://mc-api.io/render/FACE/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256");const blob = await response.blob();
document.querySelector("img").src = URL.createObjectURL(blob);

import requests
response = requests.get("https://mc-api.io/render/FACE/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256", timeout=10)response.raise_for_status()
with open("render.png", "wb") as file:    file.write(response.content)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/render/FACE/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256")).build();
HttpResponse<Path> response = client    .sendAsync(request, BodyHandlers.ofFile(Path.of("render.png")))    .join();

Try this endpoint

type

uuid or xuid

size (optional)

https://mc-api.io/render/FACE/bef1d0a8-e281-4f69-9200-64e07c235c96?size=256

GET/render/{type}/{name}/{edition}

Render a player's skin by their name and edition.

Operation IDrenderTypeByNameAndEdition

Path parameters

Path parameters of GET /render/{type}/{name}/{edition}
Name	Type	Required	Example
type	string	Yes	`FACE`
`FACEHEADBUSTFULL`
name	string	Yes	`ByteException_`
edition	string	Yes	`JAVA`
`JAVABEDROCK`

Query parameters

Query parameters of GET /render/{type}/{name}/{edition}
Name	Type	Required	Example
size	integerint32	No	`256`
Size of the rendered image in pixels. Values outside the supported range are clamped. Ceilings differ per render type: FACE reaches 1024 px, HEAD and BUST cap at 512 px, and FULL caps at 512 × 832. Range 8 – 1024

Responses

Responses of GET /render/{type}/{name}/{edition}
Status	Body	Description
200	image/png	Returns the rendered skin of the given player.
400		Returns if the given render type or size is unknown.
500		Returns if an internal server error occurred.

Example image

Example response of GET /render/{type}/{name}/{edition}

Responds with image/png. Use the URL directly in an img tag.

Request

curl -s "https://mc-api.io/render/FACE/ByteException_/JAVA?size=256" -o render.png

const response = await fetch("https://mc-api.io/render/FACE/ByteException_/JAVA?size=256");const blob = await response.blob();
document.querySelector("img").src = URL.createObjectURL(blob);

import requests
response = requests.get("https://mc-api.io/render/FACE/ByteException_/JAVA?size=256", timeout=10)response.raise_for_status()
with open("render.png", "wb") as file:    file.write(response.content)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/render/FACE/ByteException_/JAVA?size=256")).build();
HttpResponse<Path> response = client    .sendAsync(request, BodyHandlers.ofFile(Path.of("render.png")))    .join();

Try this endpoint

type

name

edition

size (optional)

https://mc-api.io/render/FACE/ByteException_/JAVA?size=256

Name

Get the name of a player by their uuid or xuid.

GET/name/{uuid or xuid}

Get the name of a player by their uuid.

Operation IDgetNameByUuidgetNameByXuid

Path parameters

Path parameters of GET /name/{uuid or xuid}
Name	Type	Required	Example
One path segment, 2 accepted formats - send exactly one:
uuid	stringuuid	One of	`bef1d0a8-e281-4f69-9200-64e07c235c96`
Get the name of a player by their uuid.
xuid	integerint64	One of	`2535439361006376`
Get the name of a bedrock player by their xuid.

Responses

Responses of GET /name/{uuid or xuid}
Status	Body	Description
200	application/jsonNameDocument	Returns the name of the player.
404		Returns if no player was found for the given input.
500		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if an upstream service is currently unavailable.

Example response

application/json

{  "name": "ByteException_",  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "cachedAt": 1704063600000}

Request

curl -s "https://mc-api.io/name/bef1d0a8-e281-4f69-9200-64e07c235c96"

const response = await fetch("https://mc-api.io/name/bef1d0a8-e281-4f69-9200-64e07c235c96");
if (!response.ok) {  const { message } = await response.json();  throw new Error(message);}
const name = await response.json();console.log(name);

import requests
response = requests.get("https://mc-api.io/name/bef1d0a8-e281-4f69-9200-64e07c235c96", timeout=10)response.raise_for_status()
name = response.json()print(name)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/name/bef1d0a8-e281-4f69-9200-64e07c235c96")).build();
HttpResponse<String> response = client.sendAsync(request, BodyHandlers.ofString()).join();System.out.println(response.body());

Try this endpoint

uuid or xuid

https://mc-api.io/name/bef1d0a8-e281-4f69-9200-64e07c235c96

UUID

Get the uuid of a player by their name.

GET/uuid/{name}

Get the uuid of a Java player by their name.

Operation IDgetUuidByName

Path parameters

Path parameters of GET /uuid/{name}
Name	Type	Required	Example
name	string	Yes	`ByteException_`

Responses

Responses of GET /uuid/{name}
Status	Body	Description
200	application/jsonUUIDDocument	Returns the uuid of the given player, including the xuid for bedrock players.
400		Returns if the given name cannot belong to that edition.
404		Returns if no player was found for the given input.
500		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if an upstream service is currently unavailable.

Example response

application/json

{  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "xuid": 2535439361006376,  "cachedAt": 1704063600000}

Request

curl -s "https://mc-api.io/uuid/ByteException_"

const response = await fetch("https://mc-api.io/uuid/ByteException_");
if (!response.ok) {  const { message } = await response.json();  throw new Error(message);}
const uuid = await response.json();console.log(uuid);

import requests
response = requests.get("https://mc-api.io/uuid/ByteException_", timeout=10)response.raise_for_status()
uuid = response.json()print(uuid)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/uuid/ByteException_")).build();
HttpResponse<String> response = client.sendAsync(request, BodyHandlers.ofString()).join();System.out.println(response.body());

Try this endpoint

name

https://mc-api.io/uuid/ByteException_

GET/uuid/{name}/{edition}

Get the uuid of a player by their name and edition.

Operation IDgetUuidByNameAndEdition

Path parameters

Path parameters of GET /uuid/{name}/{edition}
Name	Type	Required	Example
name	string	Yes	`ByteException_`
edition	string	Yes	`JAVA`
`JAVABEDROCK`

Responses

Responses of GET /uuid/{name}/{edition}
Status	Body	Description
200	application/jsonUUIDDocument	Returns the uuid of the given player, including the xuid for bedrock players.
400		Returns if the given name cannot belong to that edition.
404		Returns if no player was found for the given input.
500		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if an upstream service is currently unavailable.

Example response

application/json

{  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "xuid": 2535439361006376,  "cachedAt": 1704063600000}

Request

curl -s "https://mc-api.io/uuid/ByteException_/JAVA"

const response = await fetch("https://mc-api.io/uuid/ByteException_/JAVA");
if (!response.ok) {  const { message } = await response.json();  throw new Error(message);}
const uuid = await response.json();console.log(uuid);

import requests
response = requests.get("https://mc-api.io/uuid/ByteException_/JAVA", timeout=10)response.raise_for_status()
uuid = response.json()print(uuid)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/uuid/ByteException_/JAVA")).build();
HttpResponse<String> response = client.sendAsync(request, BodyHandlers.ofString()).join();System.out.println(response.body());

Try this endpoint

name

edition

https://mc-api.io/uuid/ByteException_/JAVA

Favicon

Get the favicon of a Java Minecraft server.

GET/favicon/{host}

Get the favicon of a server by its host, deriving the port.

Operation IDgetFaviconByHost

Path parameters

Path parameters of GET /favicon/{host}
Name	Type	Required	Example
host	string	Yes	`hypixel.net`

Responses

Responses of GET /favicon/{host}
Status	Body	Description
200	image/png	Returns the favicon of the server.
400		Returns if the given host is not a valid hostname or ip address.
404		Returns if the server has no usable favicon.
500		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if the server could not be pinged at all.

Example image

Responds with image/png. Use the URL directly in an img tag.

Request

curl -s "https://mc-api.io/favicon/hypixel.net" -o favicon.png

const response = await fetch("https://mc-api.io/favicon/hypixel.net");const blob = await response.blob();
document.querySelector("img").src = URL.createObjectURL(blob);

import requests
response = requests.get("https://mc-api.io/favicon/hypixel.net", timeout=10)response.raise_for_status()
with open("favicon.png", "wb") as file:    file.write(response.content)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/favicon/hypixel.net")).build();
HttpResponse<Path> response = client    .sendAsync(request, BodyHandlers.ofFile(Path.of("favicon.png")))    .join();

Try this endpoint

host

https://mc-api.io/favicon/hypixel.net

GET/favicon/{host}/{port}

Get the favicon of a server by its host and port.

Operation IDgetFaviconByHostAndPort

Path parameters

Path parameters of GET /favicon/{host}/{port}
Name	Type	Required	Example
host	string	Yes	`hypixel.net`
port	integerint32	Yes	`25565`

Responses

Responses of GET /favicon/{host}/{port}
Status	Body	Description
200	image/png	Returns the favicon of the server.
400		Returns if the given host is not a valid hostname or ip address, or the given port is outside the valid range.
404		Returns if the server has no usable favicon.
500		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if the server could not be pinged at all.

Example image

Responds with image/png. Use the URL directly in an img tag.

Request

curl -s "https://mc-api.io/favicon/hypixel.net/25565" -o favicon.png

const response = await fetch("https://mc-api.io/favicon/hypixel.net/25565");const blob = await response.blob();
document.querySelector("img").src = URL.createObjectURL(blob);

import requests
response = requests.get("https://mc-api.io/favicon/hypixel.net/25565", timeout=10)response.raise_for_status()
with open("favicon.png", "wb") as file:    file.write(response.content)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/favicon/hypixel.net/25565")).build();
HttpResponse<Path> response = client    .sendAsync(request, BodyHandlers.ofFile(Path.of("favicon.png")))    .join();

Try this endpoint

host

port

https://mc-api.io/favicon/hypixel.net/25565

Server

Get information about a server by host and port.

GET/server/{edition}/{host}

Get the status of a server by its host, deriving the port.

Operation IDgetServerByHost

Path parameters

Path parameters of GET /server/{edition}/{host}
Name	Type	Required	Example
edition	string	Yes	`JAVA`
`JAVABEDROCK`
host	string	Yes	`hypixel.net`

Responses

Responses of GET /server/{edition}/{host}
Status	Body	Description
200	application/jsonServerDocument	Returns the server information of the given address. A server that does not answer is reported as offline, not as an error.
400		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		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if the server could not be pinged at all.

Example response

application/json

{  "online": true,  "hostname": "hypixel.net",  "address": "mc.hypixel.net",  "port": 25565,  "ping": 100,  "motd": "§aMinecraft §7Server",  "rawMotd": "Minecraft Server",  "version": "1.20.1",  "protocol": 754,  "onlinePlayers": 100,  "maxPlayers": 1000,  "players": [    "ByteException_",    "Notch"  ],  "favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8...",  "cachedAt": 1704063600000}

Request

curl -s "https://mc-api.io/server/JAVA/hypixel.net"

const response = await fetch("https://mc-api.io/server/JAVA/hypixel.net");
if (!response.ok) {  const { message } = await response.json();  throw new Error(message);}
const server = await response.json();console.log(server);

import requests
response = requests.get("https://mc-api.io/server/JAVA/hypixel.net", timeout=10)response.raise_for_status()
server = response.json()print(server)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/server/JAVA/hypixel.net")).build();
HttpResponse<String> response = client.sendAsync(request, BodyHandlers.ofString()).join();System.out.println(response.body());

Try this endpoint

edition

host

https://mc-api.io/server/JAVA/hypixel.net

GET/server/{edition}/{host}/{port}

Get the status of a server by its host and port.

Operation IDgetServerByHostAndPort

Path parameters

Path parameters of GET /server/{edition}/{host}/{port}
Name	Type	Required	Example
edition	string	Yes	`JAVA`
`JAVABEDROCK`
host	string	Yes	`hypixel.net`
port	integerint32	Yes	`25565`

Responses

Responses of GET /server/{edition}/{host}/{port}
Status	Body	Description
200	application/jsonServerDocument	Returns the server information of the given address. A server that does not answer is reported as offline, not as an error.
400		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		Returns if an internal server error occurred.
502		Returns if an upstream service answered with something unusable.
503		Returns if the server could not be pinged at all.

Example response

application/json

{  "online": true,  "hostname": "hypixel.net",  "address": "mc.hypixel.net",  "port": 25565,  "ping": 100,  "motd": "§aMinecraft §7Server",  "rawMotd": "Minecraft Server",  "version": "1.20.1",  "protocol": 754,  "onlinePlayers": 100,  "maxPlayers": 1000,  "players": [    "ByteException_",    "Notch"  ],  "favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8...",  "cachedAt": 1704063600000}

Request

curl -s "https://mc-api.io/server/JAVA/hypixel.net/25565"

const response = await fetch("https://mc-api.io/server/JAVA/hypixel.net/25565");
if (!response.ok) {  const { message } = await response.json();  throw new Error(message);}
const server = await response.json();console.log(server);

import requests
response = requests.get("https://mc-api.io/server/JAVA/hypixel.net/25565", timeout=10)response.raise_for_status()
server = response.json()print(server)

HttpClient client = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder(URI.create("https://mc-api.io/server/JAVA/hypixel.net/25565")).build();
HttpResponse<String> response = client.sendAsync(request, BodyHandlers.ofString()).join();System.out.println(response.body());

Try this endpoint

edition

host

port

https://mc-api.io/server/JAVA/hypixel.net/25565

Schemas

The JSON documents the endpoints return. Fields are omitted when the API has no value for them, so treat every field as optional unless the endpoint description says otherwise.

UUIDDocument

Fields of UUIDDocument
Field	Type	Example
uuid	stringuuid	`bef1d0a8-e281-4f69-9200-64e07c235c96`
The UUID of the player
xuid	integerint64	`2535439361006376`
The XUID of the player.
cachedAt	integerint64	`1704063600000`
The timestamp when the document was cached.

Example

application/json

{  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "xuid": 2535439361006376,  "cachedAt": 1704063600000}

ServerDocument

Fields of ServerDocument
Field	Type	Example
online	boolean	`true`
Whether the server is online or not.
hostname	string	`hypixel.net`
The hostname of the server.
address	string	`mc.hypixel.net`
The address of the server.
port	integerint32	`25565`
The port of the server.
ping	integerint64	`100`
The ping of the server in milliseconds.
motd	string	`§aMinecraft §7Server`
The MOTD of the server.
rawMotd	string	`Minecraft Server`
The raw MOTD of the server.
version	string	`1.20.1`
The version of the server.
protocol	integerint32	`754`
The protocol of the server.
onlinePlayers	integerint32	`100`
The amount of online players on the server.
maxPlayers	integerint32	`1000`
The maximum amount of players on the server.
players	array of string
The list of online players on the server.
favicon	string	`data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8...`
The favicon of the server.
cachedAt	integerint64	`1704063600000`
The timestamp when the server document was cached.

Example

application/json

{  "online": true,  "hostname": "hypixel.net",  "address": "mc.hypixel.net",  "port": 25565,  "ping": 100,  "motd": "§aMinecraft §7Server",  "rawMotd": "Minecraft Server",  "version": "1.20.1",  "protocol": 754,  "onlinePlayers": 100,  "maxPlayers": 1000,  "players": [    "ByteException_",    "Notch"  ],  "favicon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8...",  "cachedAt": 1704063600000}

ProfileDocument

Fields of ProfileDocument
Field	Type	Example
name	string	`ByteException_`
The name of the player.
uuid	stringuuid	`bef1d0a8-e281-4f69-9200-64e07c235c96`
The UUID of the player.
xuid	integerint64	`2535439361006376`
The XUID of the player.
textures	map of string
The textures of the player.
decodedTexture	map of object
The decoded textures of the player, without the timestamp the session server stamps them with.
names	map of integerint64
A map of all names the player has used
cachedAt	integerint64	`1704063600000`
The timestamp when the document was cached.

Example

application/json

{  "name": "ByteException_",  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "xuid": 2535439361006376,  "textures": {    "signature": "...",    "value": "..."  },  "decodedTexture": {    "profileId": "bef1d0a8e2814f69920064e07c235c96",    "profileName": "ByteException_",    "textures": {      "SKIN": {        "url": "https://textures.minecraft.net/texture/..."      },      "CAPE": {        "url": "https://textures.minecraft.net/texture/..."      }    }  },  "names": {    "ByteException_": 1704063600000  },  "cachedAt": 1704063600000}

NameDocument

Fields of NameDocument
Field	Type	Example
name	string	`ByteException_`
The name of the player
uuid	stringuuid	`bef1d0a8-e281-4f69-9200-64e07c235c96`
The UUID of the player
cachedAt	integerint64	`1704063600000`
The timestamp when the document was cached.

Example

application/json

{  "name": "ByteException_",  "uuid": "bef1d0a8-e281-4f69-9200-64e07c235c96",  "cachedAt": 1704063600000}