API Documentation
Documentation on how to integrate our API in your service
Overview
The goal of this API documentation is to accurately and precisely describe the functionality of this service in plain terms. This page will go over everything you need to know before implementing our API into your service. If you believe there is anything missing, any typos, or incorrect information on this page, please reach out to me via email at [email protected].
Standards
The majority of this API uses the standardized REST API, which in simple terms means you will be making HTTP requests to our service. We currently only support endpoints using the GET and POST methods. All status endpoints return a response body in JSON format, except if the response status code is not in the 200-299 success range, in which the body will be plain text. No other data formatting standard is available at this time, and there is currently no future plan to support anything other than JSON. All JSON returned from this service will have whitespace and any unnecessary characters removed to reduce network bandwidth and wasted information. You may learn more about the properties you receive from these routes by reading the documented response body from the route on this page.
Cache
To reduce the amount of spam and deliberate denial-of-service attacks of our service, we implement a caching system for all of the data we fetch, including but not limited to status responses and server icons. Each route has its own cache duration, unique to the pathname of the request. Please note that adding query parameters to the request will not force a fresh request, it will still return the cached response. All routes with data retrieved from the cache will contain a header in the response with the key X-Cache-Hit which will contain a boolean value whether or not our service used a value from cache. The response will also contain a X-Cache-Time-Remaining header if the cache was hit, which contains an integer with the amount of seconds remaining until the cache expires for this request. Any request made after this cache expiration time will result in fresh data being retrieved on our end. No exceptions will be made to the cache duration. If you want to bypass the cache, we recommend that you self-host the ping-server available on our GitHub organization.
Rate Limiting
Since our service receives so many visitors every month, we have to implement a rate-limiting system to prevent abuse of the service. Without a rate-limit, anybody is free to request the API as fast as they want, which can overwhelm our servers with requests if your server accidentally goes haywire. Our service limits to 5 requests/second specified by client IP address. If you want to request an exception to the rate-limit, please reach out to us by emailing [email protected].
Supported Versions
All Minecraft servers, including modern and legacy Java Edition servers, and Bedrock Edition servers, are supported. Make sure you are using the correct endpoint when retrieving a server status, as attempting to use the Java Edition status route with a Bedrock Edition host (or vise-versa) will result in a response saying the server is offline unless the server explicitly has cross-play supported. If the server you specify does not use the standard port value (25565 for Java Edition, 19132 for Bedrock Edition), then you will need to specify the port by using the following format: <host>:<port>.
Query
With both Java and Bedrock Edition status routes, the API will attempt to fetch the query information in addition to the regular status information. This allows more detailed information to be retrieved, like plugins, server software, etc. To prevent excessive amounts of delay when fetching servers that do not support query, a special timeout for query has been implemented. If you fetch a server that successfully returns a status, the API will attempt to wait for only one second longer to retrieve the query before timing out. This behavior cannot be modified. Additionally, all information returned from the query will be used in favor of the status information, except for the following fields: motd, version.protocol, plugins, and software.
Error Handling
You may encounter an error from any API endpoint if you attempt to use any malformed input, such as an incorrectly formatted server address or a strange value for a query parameter. Whether or not you expect it, you should always handle in case the server returns an error, always in the form of a non-200 status code response. If you do receive a non-200 status code response, the body will always contain a plain text string describing the error, with the Content-Type header set to text/plain. An example of a standard error is Invalid address value, returned if the server address provided is not in a recognized <host>:<port> or <host> format.
Revisions
Over the lifetime of this service, there has been a few changes that breaks compatibility with existing users who rely on consistent and non-changing data. When this happens, we release a new major version of the API called a revision, which is why you see /v2 in the URL of all API requests. As time goes on, we can no longer support previous revisions and have to shut them down. You may refer to the table below to see any major revisions from the past up until present time. If you use our API, it is generally recommended to come back to this page every so often to confirm the revision you are using is not becoming deprecated.
| Revision | Base URL | Release Date | Deprecation Date | Changelog |
|---|---|---|---|---|
| Revision 1 | https://api.mcstatus.io/v1 | September 2021 | February 2023 | Initial API release |
| Revision 2 | https://api.mcstatus.io/v2 | July 2022 | — |
Routes
Java Status
Retrieves the status of any Java Edition Minecraft server. <address> should be replaced with the connection address of the server. For example, play.hypixel.net is a valid connection address as well as play.hypixel.net:25565.
GEThttps://api.mcstatus.io/v2/status/java/<address>
| Key | Data Type | Default | Description |
|---|---|---|---|
query | Boolean | true | Enables query lookup on the server, which provides additional information such as the software and plugins properties on the response. Disabling this may also speed up status retrieval times. |
timeout | Number | 5.0 | The amount of seconds until the status retrieval times out and an offline response is returned. This can also be a floating point number. |
{
// 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": "demo.mcstatus.io",
// The port of the server that was resolved from the address string.
// @type {number}
"port": 25565,
// This is the IP address that was resolved from the hostname of the server.
// It is possible that IP resolution can fail, especially if an invalid hostname
// was provided, so this property may be null.
// @type {string | null}
"ip_address": "144.172.70.183",
// Whether or not this server address has been blocked by Mojang.
// If this is true, Notchian clients will not be able to connect to the
// server via the Minecraft client because it previously violated the EULA.
// @type {boolean}
"eula_blocked": false,
// The timestamp in Unix milliseconds of when the status was retrieved from
// the Minecraft server itself.
// @type {number}
"retrieved_at": 1681883645007,
// The Unix milliseconds timestamp at which the cache will expire for this
// status. The first proceeding request made after this timestamp will
// return an up-to-date status of the server.
"expires_at": 1681883705007,
// The version data of the server. This property will be missing if the server
// is offline.
// @type {object}
"version": {
// The version name of the server, typically modified by the server
// itself to show version range. This value may contain special formatting
// characters.
// @type {string}
"name_raw": "§f1.19.4",
// The version name of the server, typically modified by the server
// itself to show version range. This value will have all formatting
// characters removed.
// @type {string}
"name_clean": "1.19.4",
// The version name of the server, typically modified by the server
// itself to show version range, as an HTML string with proper
// formatting applied.
// @type {string}
"name_html": "<span><span style=\"color: #ffffff;\">1.19.4</span></span>",
// The protocol version of the server which is used to identify
// what client versions are supported.
// @type {number}
"protocol": 762
},
// Information about the amount of players online and *some* sample
// players if provided. This property will be missing if the server
// is offline.
// @type {object}
"players": {
// The amount of online players in the server.
// @type {number}
"online": 71,
// The maximum number of allowed players in the server.
// @type {number}
"max": 100,
// Some sample players online in the server. Most (if not all) major
// servers disable this or modify the data for custom formatting. If you
// do not have any items in this array, it is because the server has
// disabled sample players for a reason.
// @type {Array.<object>}
"list": [
{
// The UUID of the player logged into the server.
// @type {string}
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
// The username of the player logged into the server. The server
// may have plugins that modify this data to show special
// formatting. This value may have formatting characters.
// @type {string}
"name_raw": "Notch",
// The username of the player logged into the server. The server
// may have plugins that modify this data to show special
// formatting. This value will not have any formatting characters.
// @type {string}
"name_clean": "Notch",
// The username of the player logged into the server, as an HTML
// string with proper formatting applied.
// @type {string}
"name_html": "<span><span style=\"color: #ffffff;\">Notch</span></span>"
}
]
},
// 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. This
// property will be missing if the server is offline.
// @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": " §c§k;;; §c§l>§6§l>§e§l> §lMinecraft Server Status §e§l<§6§l<§c§l< §c§k;;;\n §6§nhttps://mcstatus.io/",
// A clean text-only version of the MOTD with all formatting codes removed.
// @type {string}
"clean": " ;;; >>> Minecraft Server Status <<< ;;;\n https://mcstatus.io/",
// 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 class=\"minecraft-format-obfuscated\" style=\"color: #ff5555;\">;;;</span><span style=\"color: #ffffff;\"> </span><span style=\"color: #ff5555; font-weight: bold;\">></span><span style=\"color: #ffaa00; font-weight: bold;\">></span><span style=\"color: #ffff55; font-weight: bold;\">></span><span style=\"color: #ffffff;\"> </span><span style=\"color: #ffffff; font-weight: bold;\">Minecraft Server Status</span><span style=\"color: #ffffff;\"> </span><span style=\"color: #ffff55; font-weight: bold;\"><</span><span style=\"color: #ffaa00; font-weight: bold;\"><</span><span style=\"color: #ff5555; font-weight: bold;\"><</span><span style=\"color: #ffffff;\"> </span><span class=\"minecraft-format-obfuscated\" style=\"color: #ff5555;\">;;;</span><span style=\"color: #ffffff;\"></span><span style=\"color: #ffffff;\">\n </span><span style=\"color: #ffaa00; text-decoration: underline;\">https://mcstatus.io/</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. This property will also be missing if the server
// is offline.
// @type {string | null}
"icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABAEAYAAAD6...",
// Any Forge mods loaded if provided by the server. Most servers do not
// have Forge installed so this property will be empty a majority of the time.
// Legacy FML and FML2 are supported.
// @type {Array.<object>}
"mods": [
{
// The name of the mod that is loaded on the server.
// @type {string}
"name": "applied-energistics-2",
// The version of the mod that is loaded on the server.
// @type {string}
"version": "11.7.2"
}
],
// If query lookup is successful, then this property will contain the
// software that the server is running. This will be missing if the server
// is offline.
// @type {string | null}
"software": "github.com/mcstatus-io/demo-server",
// If query lookup is successful, then this property will contain the
// list of plugins that the server is running. This will be missing if the
// server is offline.
// @type {Array.<object>}
"plugins": [
{
// The name of the plugin.
// @type {string}
"name": "WorldEdit",
// The semantic version of the plugin. This property can also be null.
// @type {string | null}
"version": "7.2.14"
}
],
// The result of the SRV record lookup when acquiring the connection details
// of the server. This will always be present, even if the server is offline,
// but it will be null if no SRV record was found.
// @type {object | null}
"srv_record": {
// The hostname returned by the SRV lookup. If the SRV record exists, this
// is the actual hostname our service used to connect to the server.
// @type {string}
"host": "144.172.70.183",
// The port returned by the SRV lookup.
// @type {number}
"port": 25565
}
}Bedrock Status
Retrieves the status of any Bedrock Edition Minecraft server. <address> should be replaced with the connection address of the server. For example, pe.mineplex.com is a valid connection address as well as pe.mineplex.com:19132.
GEThttps://api.mcstatus.io/v2/status/bedrock/<address>
| Key | Data Type | Default | Description |
|---|---|---|---|
timeout | Number | 5.0 | The amount of seconds until the status retrieval times out and an offline response is returned. This can also be a floating point number. |
{
// 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": "demo.mcstatus.io",
// The port of the server that was resolved from the address string.
// @type {number}
"port": 19132,
// This is the IP address that was resolved from the hostname of the server.
// It is possible that IP resolution can fail, especially if an invalid hostname
// was provided, so this property may be null.
// @type {string | null}
"ip_address": "144.172.70.183",
// Whether or not this server address has been blocked by Mojang.
// If this is true, Notchian clients will not be able to connect to the
// server via the Minecraft client because it previously violated the EULA.
// @type {boolean}
"eula_blocked": false,
// The timestamp in Unix milliseconds of when the status was retrieved from
// the Minecraft server itself.
// @type {number}
"retrieved_at": 1681884126942,
// The Unix milliseconds timestamp at which the cache will expire for this
// status. The first proceeding request made after this timestamp will
// return an up-to-date status of the server.
"expires_at": 1681884186942,
// The version data of the server. This property will be missing if
// the server is offline.
// @type {object}
"version": {
// The version name of the server. This may be null if the server
// does not send it.
// @type {string | null}
"name": "1.19.70",
// The protocol version of the server which is used to identify
// what client versions are supported. This may be null if the server
// does not send it.
// @type {number | null}
"protocol": 575
},
// Information about the amount of online and max players. This property
// will be missing if the server is offline.
// @type {object}
"players": {
// The amount of online players in the server. This may be null if
// the server does not send it.
// @type {number | null}
"online": 71,
// The maximum number of allowed players in the server. This may be
// null if the server does not send it.
// @type {number | null}
"max": 100
},
// 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. This
// property will be missing if the server is offline.
// @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": "A Bedrock server\nYou cannot connect!",
// A clean text-only version of the MOTD with all formatting codes removed.
// @type {string}
"clean": "A Bedrock server\nYou cannot connect!",
// 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;\">A Bedrock server</span><span style=\"color: #ffffff;\">\nYou cannot connect!</span></span>"
},
// The default gamemode that players will spawn into when joining
// the server. This may be null if the server does not send it.
// @type {string | null}
"gamemode": "Survival",
// The ID of the server itself. There is little to no documentation
// online about the use of this value. This may be null if the server
// does not send it.
// @type {string | null}
"server_id": "8919800251809186875",
// The type of server that was retrieved. Possible values are "MCPE" for
// Bedrock and Pocket Edition, or "MCEE" for Education Edition. This may
// be null if the server does not send it.
// @type {"MCPE" | "MCEE" | null}
"edition": "MCPE"
}Java Widget
Returns a widget image containing information about the Java Edition server. This widget can be embedded into any website or any source that allows images via URL. The image is generated on every request, but the status of the server may be cached.
GEThttps://api.mcstatus.io/v2/widget/java/<address>
| Key | Data Type | Default | Description |
|---|---|---|---|
dark | Boolean | true | Enables dark mode for the widget image, making the background a dark gray color with the foreground text white. |
rounded | Boolean | true | Makes the corners of the widget card rounded, leaving the missing corner area transparent. |
transparent | Boolean | false | Removes the background (and border) of the generated card, allowing you to apply your own custom background. |
timeout | Number | 5.0 | The amount of seconds until the status retrieval times out and an offline response is returned. This can also be a floating point number. |
Bedrock Widget
Returns a widget image containing information about the Bedrock Edition server. This widget can be embedded into any website or any source that allows images via URL. The image is generated on every request, but the status of the server may be cached. The icon will always be the default icon since Bedrock Edition does not support custom server icons.
GEThttps://api.mcstatus.io/v2/widget/bedrock/<address>
| Key | Data Type | Default | Description |
|---|---|---|---|
dark | Boolean | true | Enables dark mode for the widget image, making the background a dark gray color with the foreground text white. |
rounded | Boolean | true | Makes the corners of the widget card rounded, leaving the missing corner area transparent. |
transparent | Boolean | false | Removes the background (and border) of the generated card, allowing you to apply your own custom background. |
timeout | Number | 5.0 | The amount of seconds until the status retrieval times out and an offline response is returned. This can also be a floating point number. |
Icon
Returns just the icon/favicon of any Java Edition Minecraft server. If connection to the server fails or if the server is offline then the default icon is returned. The address value is optional, and if not provided then the default icon is returned.
GEThttps://api.mcstatus.io/v2/icon/<address>
| Key | Data Type | Default | Description |
|---|---|---|---|
timeout | Number | 5.0 | The amount of seconds until the status retrieval times out and an offline response is returned. This can also be a floating point number. |
(actual 64×64, scaled to 128×128)
Send Vote
Allows you to send a Votifier vote to the specified server. All data should be sent as query parameters.
POSThttps://api.mcstatus.io/v2/vote
| Key | Data Type | Required | Default | Description |
|---|---|---|---|---|
host | String | Yes | — | The host of the server to send the vote to. |
port | Number | No | 8192 | The port of the Votifier server to send the vote to. |
timeout | Number | No | 5.0 | The amount of seconds until the connection times out with the server. |
username | String | Yes | — | The username of the player who is sending the vote. |
uuid | String | No | — | The UUID of the player who is sending the vote. |
serviceName | String | No | mcstatus.io | A short name of the service which is sending the vote. Typically the name of a Minecraft server listing website. |
timestamp | String | No | (time of request) | The timestamp of the vote sent to the server. This should be in RFC3339 format if provided. |
token | String | Yes** | — | The secure token used for authentication, generated by the Votifier plugin on the server. |
publickey | String | Yes** | — | The public key generated by the server. This is the contents of the rsa/public.key file. |
ip | String | No | (user IP address) | The IP address of the user sending the vote. If missing, the IP address of the client sending the request will be used. |
* Due to how Votifier 1 works, it is impossible to confirm whether a vote was successfully processed by the server. You should only receive an error if the server is offline or invalid data was supplied.
** If possible, you should be using the token query parameter if your server is running Votifier 2, as it is more secure. You can use publickey instead to ensure backwards compatibility with all Votifier servers since Votifier 2 also generates a public key. You may optionally choose to provide both values if you have them, it will attempt to use the latest version and fall back to an older protocol if necessary.
Libraries
We try and provide official support for integrating our service into many languages. The list of official and unofficial libraries are below.
Support
If you require any additional assistance or found a bug you would like to report, please send an email to [email protected]. We will be more than happy to provide any assistance.