API Documentation

Documentation on how to use 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 method. You will never have to use POST or any other method with requires you to send body data or headers with your request. All status endpoints return a response body in JSON format. 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 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.

Supported Versions

All Minecraft servers, including pre-netty rewrite Java Edition 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.

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. You can also set ?query=false in the URL query parameters to disable query lookup for faster status retrieval at the expense of missing software and plugins properties.

GEThttps://api.mcstatus.io/v2/status/java/<address>

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>

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. All query parameters are optional.

GEThttps://api.mcstatus.io/v2/widget/java/<address>?dark=<true/false>&rounded=<true/false>

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>

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].