API Documentation

Overview

mcstatus.io believes that anybody should be able to retrieve the status of any Minecraft server using a simple and efficient manner. This is why we prioritize a detailed and continuously updated documentation on how to interact with our service from yours. Please make sure to read this documentation thoroughly to prevent any errors that may be a mistake on your part.

All methods documented are using the REST API, which is supported in all major programming languages and browsers. Body data sent and received from/to the server are using JSON formatting for standardization reasons. You should familiarize yourself with this data encoding before attempting to use our service. If you have any questions, concerns or encounter any problems after attempting a solution, please feel free to contact us by sending an email to [email protected].

All server statuses are cached for up to 10 minutes from the previous network fetch. You can determine if a status was fetched from cache by using the X-Cache-Hit header returned from the server after the request. If the cache was used, there will also be a X-Cache-Time-Remaining header that will contain the amount of seconds remaining until the cache expires.

Java Status

GET https://api.mcstatus.io/v1/status/java/<address>

{
    // Determines whether the server is online or offline.
    // @type {boolean}
    "online": true,
    // The hostname of the server that was resolved from the address string.
    // @type {string}
    "host": "play.hypixel.net",
    // The port of the server that was resolved from the address string.
    // @type {number}
    "port": 25565,
    // The response object that was returned from the server with modifications
    // to properties for ease of use. This will be `null` if the server is offline.
    // @type {object | null}
    "response": {
        // The version data of the server. This will be null if the server 
        // version is pre-1.3.2.
        // @type {object | null}
        "version": {
            // The version name of the server, typically modified by the server
            // itself to show version range.
            // @type {string}
            "name": "Requires MC 1.8 / 1.18",
            // The protocol version of the server which is used to identify
            // what client versions are supported.
            // @type {number}
            "protocol": 47
        },
        // Information about the amount of players online and *some* sample
        // players if provided.
        // @type {object}
        "players": {
            // The amount of online players in the server.
            // @type {number}
            "online": 38666,
            // The maximum number of allowed players in the server.
            // @type {number}
            "max": 200000,
            // Some sample players online in the server. Most (if not all) major
            // servers disable this or modify the data for custom formatting. This
            // array may be `null`, empty or the property will be completely missing.
            // @type {Array<{ name: string, id: string } | null}
            "sample": []
        },
        // The message of the day (or MOTD/description) of the server. This is the
        // message shown below the server name in the client multiplayer menu.
        // @type {object}
        "motd": {
            // The raw MOTD with formatting codes. Refer to
            // https://minecraft.fandom.com/wiki/Formatting_codes for information
            // on how to use formatting codes.
            // @type {string}
            "raw": "                §aHypixel Network §c[1.8-1.18]\n              §6§lWOOL WARS 1.0 RELEASED",
            // A clean text-only version of the MOTD with all formatting codes removed.
            // @type {string}
            "clean": "                Hypixel Network [1.8-1.18]\n              WOOL WARS 1.0 RELEASED",
            // An HTML representation of the MOTD with proper formatting. All formatting
            // codes are supported and are equal to their value in the Minecraft fandom wiki.
            // Magic/obfuscated formatting codes are a <span> with the class `.minecraft-format-obfuscated`.
            // Line breaks are encoded as the "\n" escape code and may be replaced with <br> by the user.
            // @type {string}
            "html": "<span><span style=\"color: #ffffff;\">                </span><span style=\"color: #55ff55;\">Hypixel Network </span><span style=\"color: #ff5555;\">[1.8-1.18]</span><span style=\"color: #ffffff;\">\n              </span><span style=\"color: #ffaa00; font-weight: bold;\">WOOL WARS 1.0 RELEASED</span></span>"
        },
        // The base64-encoded PNG data of the 64x64 server icon. You may require
        // additional libraries or utilities for using this property. There are
        // several examples out there. This property may be null if the server does
        // not set an icon image.
        // @type {string | null}
        "favicon": "data:image/png;base64,...",
        // Any Forge mod information if provided by the server. Most servers do not
        // have Forge installed so this property will be null a majority of the time.
        // @type {object | null}
        "mod_info": {
            // The name of the mod loader, typically Forge.
            // @type {string}
            "type": "Forge",
            // A list of installed mods on the server.
            // @type {Array<object>}
            "mods": [
                {
                    // The name of the mod installed.
                    // @type {string}
                    "id": "Forge",
                    // The version information of the mod.
                    // @type {string}
                    "version": "1.0.0"
                }
            ]
        },
        // Some servers use an SRV record to redirect users to another host. Our
        // service correctly resolves SRV records and retrieves the status from
        // this host and port if provided.
        // @type {object | null}
        "srv_record": {
            // The hostname of the SRV record.
            // @type {string}
            "host": "...",
            // The port of the SRV record.
            // @type {number}
            "port": 25565
        }
    }
}

Bedrock Status

GET https://api.mcstatus.io/v1/status/bedrock/<address>

{
    // Determines whether the server is online or offline.
    // @type {boolean}
    "online": true,
    // The hostname of the server that was resolved from the address string.
    // @type {string}
    "host": "play.nethergames.org",
    // The port of the server that was resolved from the address string.
    // @type {number}
    "port": 19132,
    // The response object that was returned from the server with modifications
    // to properties for ease of use. This will be `null` if the server is offline.
    // @type {object | null}
    "response": {
        // The GUID of the server itself. There is little to no documentation
        // online about the use of this value.
        // @type {number}
        "server_guid": 3037183795130687807,
        // The type of server that was retrieved. Possible values are "MCPE" for
        // Bedrock and Pocket Edition, or "MCEE" for Education Edition.
        // @type {"MCPE" | "MCEE"}
        "edition": "MCPE",
        // The message of the day (or MOTD/description) of the server. This is the
        // message shown below the server name in the client multiplayer menu.
        // @type {object}
        "motd": {
            // The raw MOTD with formatting codes. Refer to
            // https://minecraft.fandom.com/wiki/Formatting_codes for information
            // on how to use formatting codes.
            // @type {string}
            "raw": "§e§lN§6G§7: §61.18 support!\nWaterdogPE Proxy",
            // A clean text-only version of the MOTD with all formatting codes removed.
            // @type {string}
            "clean": "NG: 1.18 support!\nWaterdogPE Proxy",
            // An HTML representation of the MOTD with proper formatting. All formatting
            // codes are supported and are equal to their value in the Minecraft fandom wiki.
            // Magic/obfuscated formatting codes are a <span> with the class `.minecraft-format-obfuscated`.
            // Line breaks are encoded as the "\n" escape code and may be replaced with <br> by the user.
            // @type {string}
            "html": "<span><span style=\"color: #ffff55; font-weight: bold;\">N</span><span style=\"color: #ffaa00;\">G</span><span style=\"color: #aaaaaa;\">: </span><span style=\"color: #ffaa00;\">1.18 support!</span><span style=\"color: #ffffff;\">\nWaterdogPE Proxy</span></span>"
        },
        // The protocol version of the server which is used to identify
        // what client versions are supported.
        // @type {number}
        "protocol_version": 503,
        // The version name of the server shown on the multiplayer menu.
        // @type {string}
        "version": "1.18.30",
        // The amount of online players in the server.
        // @type {number}
        "online_players": 571,
        // The maximum number of allowed players in the server.
        // @type {number}
        "max_players": 576,
        // The ID of the server itself. There is little to no documentation
        // online about the use of this value.
        // @type {string}
        "server_id": "3037183795130687807",
        // The default gamemode that players will spawn into when joining
        // the server.
        // @type {string}
        "gamemode": "Survival",
        // The type ID of the gamemode that players will spawn into when
        // joining the server. Directly correlates to the property above.
        // @type {number}
        "gamemode_id": 1,
        // The port to use when connecting to the server using an IPv4 address.
        // @type {number}
        "port_ipv4": 19132,
        // The port to use when connecting to the server using an IPv6 address.
        // @type {number}
        "port_ipv6": 19132,
        // Some servers use an SRV record to redirect users to another host. Our
        // service correctly resolves SRV records and retrieves the status from
        // this host and port if provided.
        // @type {object | null}
        "srv_record": {
            // The hostname of the SRV record.
            // @type {string}
            "host": "...",
            // The port of the SRV record.
            // @type {number}
            "port": 25565
        }
    }
}

Favicon

GET https://api.mcstatus.io/v1/favicon/<address>/<filename>.png

Sample icon of Hypixel