Realms API

The Minecraft Realms API is the API endpoint used to control worlds hosted by Mojang's Minecraft Realms service. This is a paid service provided to abstract managing a Minecraft server. More information on this can be found at https://minecraft.net/realms.

The API endpoint for the Desktop Edition is located at https://mcoapi.minecraft.net. This is where all requests, as listed on this page, should be sent to.

There is also an endpoint for Pocket Edition in development, located at https://peoapi.minecraft.net. It is being documented at Pocket Realms

Sessions

Session identification is stored in a pair of cookies sent with the header of every request. The only required header within a request is having this cookie set.

Key	Value
sid	This is the current session ID of the logged in user. This follows the format of: token:<accessToken>:<player UUID>
user	This is the username of the logged in user. This value is case sensitive.
version	The version of the Minecraft instance running.

An example request:

GET /mco/available HTTP/1.1
Cookie: sid=<token>;user=Herobrine;version=1.7.9
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.6.0_27
Host: mcoapi.minecraft.net
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

Notes

As per standard HTTP, a GET request has no parameters, and a POST request can potentially contain content (Note, several POST requests below has empty content).

Defining a server

For most endpoints requiring a server, it is returned in a JSON object format, containing the following values:

Key	Value	Value Type
activeSlot	Unknown, seems to always return '1'	Integer
daysLeft	How many days are left of subscription. Always returns '0' if not owner and returns '-1' if expired	Integer
expired	Whether the subscription has expired	Boolean
expiredTrial	Whether the trial subscription has expired	Boolean
id	The ID of the server. Must be unique	Integer
maxPlayers	The max players of the server, always returns '10'	Integer
member	Unknown, possibly returns `true` if OP?	Boolean
minigameId	Not confirmed, probably unique Id of Minigame map. Returns `null` if not in a minigame	Integer
minigameImage	Not confirmed, probably base64 encoded or url thumbnail for minigame. Returns `null` if not in a minigame	String
minigameName	Not confirmed, probably name of minigame that is currently active. Returns `null` if not in a minigame	String
motd	The MOTD of the server. Doesn't support color.	String
name	The name of the server	String
owner	The owner of the server. If this is equal to the previewing players username, the configure button will be accessible.	String
ownerUUID	The unique ID of the owner	String
players	A array of currently connected players?	JSON Array, with string values
remoteSubscriptionId	Unknown, perhaps linked to transaction? Seems to work if same as 'id'	String
slots	Unknown, returns `null`	Unknown
state	The status of the server. Can be one of the following: ADMIN_LOCK, CLOSED, OPEN, UNINITIALIZED	String
worldType	Unknown, default is "NORMAL", perhaps linked to minigame?	String

Endpoints

GET requests

GET /mco/available

Returns whether the user can access the Minecraft Realms service. This request does not require a Cookie token to be sent.

Returns: plain text; only observed value is

true

Prior to Realms release, this returned false.

GET /mco/client/outdated

Returns whether the clients version is up to date with Realms. This is checked against the Cookie token.

Returns: Boolean value, if the client is outdated, it returns true, else, it returns false.

GET /worlds

Return a list of servers that the user is invited to or owns.

Returns: a JSON object with one array. Each element within the array represents a server.

Key	Value	Value Type
servers	A array of servers	JSON array of Servers

Example:

{"worlds": [
   {"id": 1,
   "remoteSubscriptionId": "1",
   "name": "A Test Server",
   "players": ["Notch"],
   "motd": "This is a testing server!",
   "state": "OPEN",
   "owner": "j_selby",
   "daysLeft": 30,
   "ip": "localhost:25565",
   "expired": false,
   "minigame": false}, ...
]}

GET /worlds/$ID

Returns a single server listing about a server. If you are not the owner of the server, the server will return a 403 error, with a JSON encoded error message.

Returns: a JSON encoded Server, as above.

GET /worlds/$ID/join

Requires TOS to be agreed to (as below).

Used to get the IP address for a server.

If a server doesn't exist/you do not have currently have access to it, the server will return a 404 error, with no content.

Returns:

Key	Value	Value Type
address	The address of a server, encoded as [IP]:[Port]	String

GET /worlds/$ID/backups

Returns a list of backups for the world.

If a server doesn't exist/you do not have currently have access to it, the server will return a 403 error, with no content.

Returns: a JSON encoded list of backups for the specified world ID

GET /worlds/$ID/slot/$WORLD(1-4)/download

Get the download URL of the latest backup.

Returns a json response like:

{
	"downloadLink": "http://us-west-mcr-worlds.s3.amazonaws.com/dfasdfa/mcr_world.tar.gz?AWSAccessKeyId=ADSFASDFADSF&Expires=1457647137&Signature=ADSFASDFASDF",
	"resourcePackUrl": null,
	"resourcePackHash": null
}

GET /ops/$ID

Returns a list of operators for this server. You must own this server to view this.

Returns:

Key	Value	Value Type
ops	A array of player names	JSON array of Strings

GET /subscriptions/$ID

Returns the current life of a server subscription.

Returns:

Key	Value	Value Type
startDate	A millisecond value. This is measured from January 1, 1970.	Long
daysLeft	The amount of days left within this subscription	Integer
subscriptionType	The kind of subscription this user has. This has been seen to be NORMAL or RECURRING.	String

GET /mco/buy

Displays a status message to the user, along with a link to the Mojang website.

Returns:

Key	Value	Value Type
statusMessage	The message displayed to the user	String
buyLink	A URL to the purchase website. Optional. If not provided, no link is shown	String

GET /invites/count/pending

Returns the amount of invites the player currently has waiting.

Returns: Integer value

POST requests

POST /mco/tos/agreed

To join Realms servers, you must agree to the TOS. Sending a blank POST request to this endpoint will set this flag.