API Documentation

As you may know from the About us page, we have the modules system, which allows to do multiple things with one request. This works with Query parameters (text after ? in the URL). For example, if you want to get the server Java and Bedrock status in one time, you can just send HTTP GET request to https://statusmc.perchun.it/api/v1/myserver.net?modules=java,bedrock.

Our API server will send a Java status request to myserver.net:25565 and Bedrock status request to myserver.net:19132. (Those ports are guessed automatically: if no port specified, we will try 19132 for Bedrock and 25565 (or SRV record) for Java. You can specify the port adding :port to the end of the hostname, for example myserver.net:12345).

But what about Java status and Query? Those cannot be hosted on one port, so you need to use another one (e.g. 25566). In the modules system, we can specify completely different IP for every module. For example, if you want to get Java status from myserver.net:25565 and Query from myserver.net:25566, you can send HTTP GET request to https://statusmc.perchun.it/api/v1/i_am_ignored?modules=java,query&to_java=myserver.net:25565&to_query=myserver.net:25566. (For example, if you will not specify &to_java=, the API will use IP from the URL as fallback (in upper example, it’s i_am_ignored).)

It’s not limited to only ports, but also to completely different IPs: https://statusmc.perchun.it/api/v1/hypixel.net?modules=java,bedrock&to_bedrock=mco.cubecraft.net. This works with Query too!

Few answers in one? How?

This is the simplest part. Each module provides property in answer, that is named as module. For example, if you will ask for Java status, the answer will be a JSON object with java property where the answer is stored. In this property, there will be Java status answer object, there is a description of it in the end of the page.

{ "java": {...} }

So if you will request all possible modules (java, bedrock, query) - there will be three properties with three different answers:

{
  "java": {...},
  "bedrock": {...},
  "query": {...}
}

// Determines whether the server is online or offline.
// Is `false` only in the Offline scheme.
online: boolean = true
// The server's address information
address: object = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Message Of The Day aka server's description.
motd: StringWithFormatting = {
  // The raw format, with Minecraft's formatting codes.
  minecraft: string
  // The plain format. There are no formatting codes, only plain text.
  plain: string
  // The HTML format. It's a string with HTML tags.
  // Note that it's wrapped in `<p>` tag, so you may want to remove it.
  html: string
  // ANSI 24-bit format aka format for colored text in the terminal.
  ansi: string
  // You may want to write other formats yourself, use underlying library
  // mcstatus for this. They have really powerful API for MOTD transformers.
  // https://github.com/py-mine/mcstatus
}
// Server's version information.
version: object = {
  // Human readable version name. It may contain formatting codes, so
  // it's parsed the same as it parses MOTD. It's sent by the server,
  // so expect that it can be modified.
  name: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Internal Minecraft protocol version.
  // See https://minecraft.fandom.com/wiki/Protocol_version#List_of_protocol_versions
  protocol: number = 47
}
// Info about the server's players that are currently online.
players: object = {
  // Current number of players that are on this server.
  online: number
  // Maximum number of players that can be on this server.
  max: number
  // List of players that are currently on this server.
  // Vanilla Minecraft server core limits it to 7 people.
  // Most of the major servers disable this feature, and instead
  // put there some ad. Can be not present, if server disabled
  // it completely.
  list: list of objects = [
    {
      // Name of the Player. If server replaced it with ad, there
      // will be formatting codes that are parsed the same as MOTD
      // is parsed.
      name: StringWithFormatting = {
        // See `motd` above for attribute descriptions here.
      }
      // The UUID of the player. Can be set to zeros if the server
      // use this list as ad. Don't expect to be it as something meaningful
      // on pirate servers.
      uuid: string
    }
  ]
}
// Base64 encoded favicon image. Can be not present if server
// doesn't have it.
icon: string
// Additional information about the server, that our parser didn't
// parse. It may not be a part of the official protocol, so don't
// expect it to be present.
additional: object
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645667116
}

// Determines whether the server is online or offline.
// Is `false` only in the Offline scheme.
online: boolean = true
// The server's address information
address: object = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Message Of The Day aka server's description.
motd: StringWithFormatting = {
  // The raw format, with Minecraft's formatting codes.
  minecraft: string
  // The plain format. There are no formatting codes, only plain text.
  plain: string
  // The HTML format. It's a string with HTML tags.
  // Note that it's wrapped in `<p>` tag, so you may want to remove it.
  html: string
  // ANSI 24-bit format aka format for colored text in the terminal.
  ansi: string
  // You may want to write other formats yourself, use underlying library
  // mcstatus for this. They have really powerful API for MOTD transformers.
  // https://github.com/py-mine/mcstatus
}
// Server's version information.
version: object = {
  // Human readable version name. It may contain formatting codes, so
  // it's parsed the same as it parses MOTD. It's sent by the server,
  // so expect that it can be modified.
  name: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Internal Minecraft protocol version.
  // See https://minecraft.fandom.com/wiki/Protocol_version#List_of_protocol_versions
  protocol: number = 47
}
// Info about the server's players that are currently online.
players: object = {
  // Current number of players that are on this server.
  online: number
  // Maximum number of players that can be on this server.
  max: number
  // List of players that are currently on this server.
  // Vanilla Minecraft server core limits it to 7 people.
  // Most of the major servers disable this feature, and instead
  // put there some ad. Can be not present, if server disabled
  // it completely.
  list: list of objects = [
    {
      // Name of the Player. If server replaced it with ad, there
      // will be formatting codes that are parsed the same as MOTD
      // is parsed.
      name: StringWithFormatting = {
        // See `motd` above for attribute descriptions here.
      }
      // The UUID of the player. Can be set to zeros if the server
      // use this list as ad. Don't expect to be it as something meaningful
      // on pirate servers.
      uuid: string
    }
  ]
}
// Base64 encoded favicon image. Can be not present if server
// doesn't have it.
icon: string
// Additional information about the server, that our parser didn't
// parse. It may not be a part of the official protocol, so don't
// expect it to be present.
additional: object
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645667116
}

// Determines whether the server is online or offline.
// Is `false` only in the Offline scheme.
online: boolean = true
// The server's address information
address: object = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Message Of The Day aka server's description.
motd: StringWithFormatting = {
  // The raw format, with Minecraft's formatting codes.
  minecraft: string
  // The plain format. There are no formatting codes, only plain text.
  plain: string
  // The HTML format. It's a string with HTML tags.
  // Note that it's wrapped in `<p>` tag, so you may want to remove it.
  html: string
  // ANSI 24-bit format aka format for colored text in the terminal.
  ansi: string
  // You may want to write other formats yourself, use underlying library
  // mcstatus for this. They have really powerful API for MOTD transformers.
  // https://github.com/py-mine/mcstatus
}
// Server's version information.
version: object = {
  // Human readable version name. It may contain formatting codes, so
  // it's parsed the same as it parses MOTD. It's sent by the server,
  // so expect that it can be modified.
  name: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Pocket Edition (now it's Bedrock Edition) or Education Edition.
  // Some custom implementations can change it to something else,
  // but generally expect only these values.
  edition: "MCPE" or "MCEE" = "MCPE"
  // Internal Minecraft protocol version.
  // See https://minecraft.fandom.com/wiki/Protocol_version#List_of_protocol_versions
  protocol: number = 47
}
// Info about the server's players that are currently online.
players: object = {
  // Current number of players that are on this server.
  online: number
  // Maximum number of players that can be on this server.
  max: number
}
// The name of the map. May be modified, but mostly it's `world`.
map_name: string
// The default gamemode on the server. New players spawn with it.
gamemode: string
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645667116
}

// Determines whether the server is online or offline.
// Is `false` only in the Offline scheme.
online: boolean = true
// The server's address information
address: object = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Message Of The Day aka server's description.
motd: StringWithFormatting = {
  // The raw format, with Minecraft's formatting codes.
  minecraft: string
  // The plain format. There are no formatting codes, only plain text.
  plain: string
  // The HTML format. It's a string with HTML tags.
  // Note that it's wrapped in `<p>` tag, so you may want to remove it.
  html: string
  // ANSI 24-bit format aka format for colored text in the terminal.
  ansi: string
  // You may want to write other formats yourself, use underlying library
  // mcstatus for this. They have really powerful API for MOTD transformers.
  // https://github.com/py-mine/mcstatus
}
// Server's version information.
version: object = {
  // Human readable version name. It may contain formatting codes, so
  // it's parsed the same as it parses MOTD. It's sent by the server,
  // so expect that it can be modified.
  name: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Pocket Edition (now it's Bedrock Edition) or Education Edition.
  // Some custom implementations can change it to something else,
  // but generally expect only these values.
  edition: "MCPE" or "MCEE" = "MCPE"
  // Internal Minecraft protocol version.
  // See https://minecraft.fandom.com/wiki/Protocol_version#List_of_protocol_versions
  protocol: number = 47
}
// Info about the server's players that are currently online.
players: object = {
  // Current number of players that are on this server.
  online: number
  // Maximum number of players that can be on this server.
  max: number
}
// The name of the map. May be modified, but mostly it's `world`.
map_name: string
// The default gamemode on the server. New players spawn with it.
gamemode: string
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645667116
}

// Determines whether the server is online or offline.
// Is `false` only in the Offline scheme.
online: boolean = true
// The server's address information
address: object = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Message Of The Day aka server's description.
motd: StringWithFormatting = {
  // The raw format, with Minecraft's formatting codes.
  minecraft: string
  // The plain format. There are no formatting codes, only plain text.
  plain: string
  // The HTML format. It's a string with HTML tags.
  // Note that it's wrapped in `<p>` tag, so you may want to remove it.
  html: string
  // ANSI 24-bit format aka format for colored text in the terminal.
  ansi: string
  // You may want to write other formats yourself, use underlying library
  // mcstatus for this. They have really powerful API for MOTD transformers.
  // https://github.com/py-mine/mcstatus
}
// Server's version information.
version: object = {
  // Human readable version name. It may contain formatting codes, so
  // it's parsed the same as it parses MOTD. It's sent by the server,
  // so expect that it can be modified.
  name: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Server's core. Can be modified by custom implementations, but most of the
  // plugins forgot to do it in Query. So it's usually the true server's core.
  brand: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Plugins on the server. Can be not present if server disabled it.
  plugins: list of objects = [
    {
      // Name of the plugin. It's defined in `plugin.yml`, so it
      // can't have spaces or other special characters.
      name: string
      // Version of the plugin. Defined in `plugin.yml` too.
      version: string
    }
  ]
}
// Info about the server's players that are currently online.
players: object = {
  // Current number of players that are on this server.
  online: number
  // Maximum number of players that can be on this server.
  max: number
  // List of players' names that are currently on this server.
  names: list of strings
}
// The name of the map. May be modified, but mostly it's `world`.
map_name: string
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645667116
}

// Determines whether the server is online or offline.
// Is `false` only in the Offline scheme.
online: boolean = true
// The server's address information
address: object = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Message Of The Day aka server's description.
motd: StringWithFormatting = {
  // The raw format, with Minecraft's formatting codes.
  minecraft: string
  // The plain format. There are no formatting codes, only plain text.
  plain: string
  // The HTML format. It's a string with HTML tags.
  // Note that it's wrapped in `<p>` tag, so you may want to remove it.
  html: string
  // ANSI 24-bit format aka format for colored text in the terminal.
  ansi: string
  // You may want to write other formats yourself, use underlying library
  // mcstatus for this. They have really powerful API for MOTD transformers.
  // https://github.com/py-mine/mcstatus
}
// Server's version information.
version: object = {
  // Human readable version name. It may contain formatting codes, so
  // it's parsed the same as it parses MOTD. It's sent by the server,
  // so expect that it can be modified.
  name: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Server's core. Can be modified by custom implementations, but most of the
  // plugins forgot to do it in Query. So it's usually the true server's core.
  brand: StringWithFormatting = {
    // See `motd` above for attribute descriptions here.
  }
  // Plugins on the server. Can be not present if server disabled it.
  plugins: list of objects = [
    {
      // Name of the plugin. It's defined in `plugin.yml`, so it
      // can't have spaces or other special characters.
      name: string
      // Version of the plugin. Defined in `plugin.yml` too.
      version: string
    }
  ]
}
// Info about the server's players that are currently online.
players: object = {
  // Current number of players that are on this server.
  online: number
  // Maximum number of players that can be on this server.
  max: number
  // List of players' names that are currently on this server.
  names: list of strings
}
// The name of the map. May be modified, but mostly it's `world`.
map_name: string
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645667116
}

What if the server offline?

We just replace it with other object, that has online property set to false.

// Determines whether the server is online or offline.
// It's always `false` in this model.
online: boolean = false
// The server's address information.
// If it's invalid, we set here a string provided by user.
address: object or string = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Error, which we received during the connection to the server.
error: object = {
  // Short name of the error. If you know Python, it's just `repr(error)`.
  short_name: string = "TimeoutError()"
  // Big traceback description of the error.
  // It's what print unhandled exceptions in Python.
  traceback: string = "Traceback (most recent call last):\n  File ..."
}
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645666846
}

// Determines whether the server is online or offline.
// It's always `false` in this model.
online: boolean = false
// The server's address information.
// If it's invalid, we set here a string provided by user.
address: object or string = {
  // The hostname of the server that was parsed from the address string.
  // Example if there were an SRV record.
  host: string = "play.hypixel.net"
  // The port of the server that was parsed from the address string.
  // Will be different if there was an SRV record and no port was specified.
  port: number = 25565
}
// Error, which we received during the connection to the server.
error: object = {
  // Short name of the error. If you know Python, it's just `repr(error)`.
  short_name: string = "TimeoutError()"
  // Big traceback description of the error.
  // It's what print unhandled exceptions in Python.
  traceback: string = "Traceback (most recent call last):\n  File ..."
}
// Internal info that is not sent by the server.
// It's still a part of Public API and you are free to use it.
internal: object = {
  // The time when this server answer was cached on our side.
  // Can be different from the Cloudflare's cache time.
  // Look for theirs headers if you really want to know it.
  cached_at: number = 1645666816
  // The time, when this cache will expire.
  cache_ends_at: number = 1645666846
}

Icon endpoint

You can get the icon of the server separately, on the v1/icon/{ip} endpoint. It will return the icon in PNG format. This is actually the same as doing Java status request, and decode from Base64 icon property. If you need an icon and Java status, you should do only Java status request and decode the icon from it. This will reduce the network latency (time between the moment when you sent the request and our server answered on it). The endpoint is actually doing the same. Also, if you will do two requests (for Java status and icon) - don’t worry, we cache the Java status answer, so we don’t spam the server!

The endpoint is https://statusmc.perchun.it/api/v1/icon/myserver.net. Replace the myserver.net part with your IP. This is not done as one of modules, because the endpoint return bytes that cannot be properly encoded into JSON, and even if so, there is no sense to encode those, as you can just use icon property from Java status answer with the same impact.

Supported Versions

Our API supports all modern Minecraft servers, including Bedrock and Education Edition servers. Please ensure that you use the correct module when retrieving server status. Attempting to use the Java Edition status module with a Bedrock Edition host (or vice versa) will result in a response indicating that the answer doesn’t have the property with data, that you expected.

Please inform us at statusmc@perchun.it if you will find unsupported server.

Cache

We have a cache system on our CDN (Cloudflare) which uses an URL as a key and another cache system on our backend, that caches each module individually. Second one is quite slower, but more efficient. Anyway, you’re free to spam as many requests, as you want. But note that our service is a proxy and helping tool for other humans, do not use it for example server scanners, or similar software where performance is important. You can self-host our backend server (see GitHub repository) or use the original library - mcstatus (Python).