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://pc.realms.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://pocket.realms.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.

An example request: GET /mco/available HTTP/1.1 Cookie: sid= ;user=Herobrine;version=1.14.4 Cache-Control: no-cache Pragma: no-cache User-Agent: Java/1.6.0_27 Host: pc.realms.minecraft.net Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive

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

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.

If it returns false, this screen appears :.

GET /mco/client/compatible
Returns whether the clients version is up to date with Realms. This is checked against the Cookie token.

Returns: String, if the client is outdated, it returns OUTDATED, if the client is running a snapshot, it returns OTHER, else it returns COMPATIBLE

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.

Example: {"servers":[{ "id":1, "remoteSubscriptionId":"aaaa0000bbbb1111cccc2222dddd3333", "owner":"j_selby", "ownerUUID":"3333dddd2222cccc1111bbbb0000aaaa", "name":"A Test Server", "motd":"This is a testing server!", "state":"OPEN", "daysLeft":30, "expired":false, "expiredTrial":false, "worldType":"NORMAL", "players":["Notch"], "maxPlayers":10, "minigameName":null, "minigameId":null, "minigameImage":null, "activeSlot":1, "slots":null, "member":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/v1/$ID/join/pc
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:

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

{    "backups": [ {            "backupId": "2019-09-08T18:04:53.5284117Z", "lastModifiedDate": 1567965893000, "size": 11080009, "metadata": { "game_difficulty": "1", "name": "Azerus Team", "game_server_version": "1.14.4", "enabled_packs": "{\"resourcePacks\":[],\"behaviorPacks\":[]}", "description": "§7Creators of §6Puzzle Wars§7 and §6Maze Wars             §8(l’o’l)", "game_mode": "0", "world_type": "NORMAL" }        }     ] }

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:

GET /subscriptions/$ID
Returns the current life of a server subscription.

Returns:

GET /mco/buy
Displays a status message to the user, along with a link to the Mojang website.

Returns:

GET /invites/count/pending
Returns the amount of invites the player currently has waiting.

Returns: Integer value

GET /invites/pending
Returns invites the player currently has waiting

Returns a json response like:

{    "invites": [ {            "invitationId": "21538412", "worldName": "Plagiatus' Realm", "worldDescription": "Play Slay here now!", "worldOwnerName": "Plagiatus", "worldOwnerUuid": "e75e2d263b724a93a3e7a2491f4c454f", "date": 1568125140562 }    ] }

GET /worlds/templates/$TEMPLATE?page=$PAGE&pageSize=$PAGE_SIZE
Returns already existed maps in Realms

Returns a json response like:

{    "templates": [ {            "id": 292, "name": "Maze Wars", "version": "1.0.3", "author": "Azerus Team", "link": "", "image": " ", "trailer": "https://www.youtube.com/watch?v=Ly3HRBWUxQc", "recommendedPlayers": "2+ players", "type": "MINIGAME" }    ],     "page": 5, "size": 1, "total": 55 }

GET /trial
Returns boolean type

True - you have free trial for test realms for 1 month

False - you already used your free trial month

GET /activities/liveplayerlist
Returns player activities at the moment

GET /subscriptions/$WORLD_ID
Returns a json response like: {    "startDate": 1562061319119, "daysLeft": 109, "subscriptionType": "NORMAL" }

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.

POST /ops/$WORLD_ID/$UUID
Give operator status for player by uuid

Returns a json response like:

{    "ops": [ "BrandShei", "_Juski_", "Sirboys", "Plagiatus", "Just_Vlad" ] }

POST /invites/$WORLD_ID
Invite player to Realm

Payload { 	"name":"Marc",					//Username "uuid":"b05881186e75410db2db4d3066b223f7",	//UUID "operator":false,				//optional "accepted":false,				//optional "online":false					//optional } Returns a json information about Realm:

{    "id": 123, "remoteSubscriptionId": "ID", "owner": "Notch", "ownerUUID": "069a79f444e94726a5befca90e38aaf5", "name": "Realm name", "motd": "Notch's realm", "defaultPermission": "MEMBER", "state": "OPEN", "daysLeft": 1, "expired": false, "expiredTrial": false, "gracePeriod": false, "worldType": "NORMAL", "players": [                                         //Array of all players (invited, accepted) {            "uuid": "b05881186e75410db2db4d3066b223f7", "name": "Marc", "operator": false, "accepted": false, "online": false, "permission": "MEMBER" }    ],     "maxPlayers": 10, "minigameName": null, "minigameId": null, "minigameImage": null, "activeSlot": 1, "slots": null, "member": false, "clubId": null }

PUT /worlds/minigames/$MINIGAME_ID/$WORLD_ID
Returns true if successfully set world to minigames

PUT invites/reject/$INVITATION_ID
Reject invitation from the player

Send empty message if successful

PUT /invites/accept/$INVITATION_ID
Accept invitation from the player

Send empty message if successful

PUT /worlds/$WORLD_ID/open
Opens realm

Returns true if the world has opened

PUT /worlds/$WORLD_ID/close
Close realm

Returns true if the world has closed

DELETE /invites/$WORLD_ID/invite/$UUID
Kick player from your realms even if player not accept invitation $UUID - uuid of player Returns empty message if success

DELETE /ops/$WORLD_ID/$UUID
Remove operator status for player by uuid

Returns a json response like:

{    "ops": [ "BrandShei", "_Juski_", "Sirboys", "Plagiatus", "Just_Vlad" ] }