Difference between revisions of "Realms API"

From wiki.vg
Jump to navigation Jump to search
(→‎Defining a server: Added many missing keys and reordered to structure returned JSON)
 
(46 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
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 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.
+
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://peoapi.minecraft.net. It is being documented at [[Pocket Realms]]
+
There is also an endpoint for Bedrock Edition in development, located at https://pocket.realms.minecraft.net. It is being documented at [[Bedrock Realms]]
  
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]
Line 24: Line 24:
 
An example request:
 
An example request:
 
  GET /mco/available HTTP/1.1
 
  GET /mco/available HTTP/1.1
−
  Cookie: sid=<token>;user=Herobrine;version=1.7.9
+
  Cookie: sid=<token>;user=Herobrine;version=1.14.4
 
  Cache-Control: no-cache
 
  Cache-Control: no-cache
 
  Pragma: no-cache
 
  Pragma: no-cache
 
  User-Agent: Java/1.6.0_27
 
  User-Agent: Java/1.6.0_27
−
  Host: mcoapi.minecraft.net
+
  Host: pc.realms.minecraft.net
 
  Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
 
  Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
 
  Connection: keep-alive
 
  Connection: keep-alive
  
 
== Notes ==
 
== 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).
+
As per standard HTTP, a GET request has no parameters, and a POST request can potentially contain content (Note, several POST requests below have empty content).
  
 
== Defining a server ==
 
== Defining a server ==
Line 40: Line 40:
 
! Key !! Value !! Value Type
 
! Key !! Value !! Value Type
 
|-
 
|-
−
| activeSlot || Unknown, seems to always return '1' || Integer
+
| id || The ID of the server. Must be unique || Integer
 +
|-
 +
| remoteSubscriptionId || Unknown, perhaps linked to transaction? Seems to work if same as 'id' || String
 +
|-
 +
| owner || The owner of the server. || String
 +
|-
 +
| ownerUUID || The unique ID of the owner. If this is equal to the previewing players unique ID, the configure button will be accessible. Note that the UUID haven't got hyphens|| String
 +
|-
 +
| name || The name of the server || String
 +
|-
 +
| motd || The MOTD of the server. Does support color codes, but officially color cannot be set. || String
 +
|-
 +
| state || The status of the server. Can be one of the following: CLOSED, OPEN, UNINITIALIZED || String
 
|-
 
|-
 
| daysLeft || How many days are left of subscription. Always returns '0' if not owner and returns '-1' if expired || Integer
 
| daysLeft || How many days are left of subscription. Always returns '0' if not owner and returns '-1' if expired || Integer
Line 48: Line 60:
 
| expiredTrial || Whether the trial subscription has expired || Boolean
 
| expiredTrial || Whether the trial subscription has expired || Boolean
 
|-
 
|-
−
| id || The ID of the server. Must be unique || Integer
+
| worldType || Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION)|| String
 +
|-
 +
| players || An array of currently connected players? || JSON Array, with string values
 
|-
 
|-
 
| maxPlayers || The max players of the server, always returns '10' || Integer
 
| maxPlayers || The max players of the server, always returns '10' || Integer
 
|-
 
|-
−
| member || Unknown, possibly returns `true` if OP? || Boolean
+
| minigameName ||Name of minigame that is currently active. Returns `null` if not in a minigame || String
 
|-
 
|-
 
| minigameId ||Not confirmed, probably unique Id of Minigame map. Returns `null` if not in a minigame || Integer
 
| 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
+
| minigameImage ||base64 of the current minigame image in format PNG. 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
+
| activeSlot || Current server world (1-4) || Integer
 +
|-
 +
| slots || List of worlds slots. Only visible by owner (/worlds/$ID) || Unknown
 +
|-
 +
| member || Unknown || Boolean
 
|-
 
|-
−
| motd || The MOTD of the server. Doesn't support color. || String
+
| parentWorldId || ID of the parent realm that a snapshot realm is tied to. Value of -1 on the parent realm || Integer
 
|-
 
|-
−
| name || The name of the server || String
+
| parentWorldName || Name of the parent realm that a snapshot realm is tied to || String
 
|-
 
|-
−
| owner || The owner of the server. If this is equal to the previewing players username, the configure button will be accessible. || String
+
| compatibility || Compatibility with the current game version. Can be one of the following: UNVERIFIABLE, INCOMPATIBLE, NEEDS_DOWNGRADE, NEEDS_UPGRADE, COMPATIBLE || String
 
|-
 
|-
−
| ownerUUID || The unique ID of the owner || String
+
| activeVersion || Game version of the realm || String
 +
|}
 +
 
 +
== Environments ==
 +
The environment defines the location of the API. The client supports switching between multiple different Realms environments, using an environment variable.
 +
 
 +
It can be set with <code>-Drealms.environment=</code>.
 +
 
 +
If not specified, the "PRODUCTION" environment is used.
 +
 
 +
{| class="wikitable"
 +
! Value !! API endpoint
 
|-
 
|-
−
| players || A array of currently connected players? || JSON Array, with string values
+
| PRODUCTION || https://pc.realms.minecraft.net
 
|-
 
|-
−
| remoteSubscriptionId || Unknown, perhaps linked to transaction? Seems to work if same as 'id' || String
+
| STAGE || https://pc-stage.realms.minecraft.net
−
|-  
 
−
| 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
+
| LOCAL || http://localhost:8080
−
|-
 
 
|}
 
|}
 +
 +
When set to "STAGE" or "LOCAL", the text "STAGE!" in yellow or "LOCAL!" in light green is displayed on top of the Minecraft Realms logo in the Realms menu.
  
 
== Endpoints ==
 
== Endpoints ==
Line 93: Line 119:
 
Prior to Realms release, this returned false.
 
Prior to Realms release, this returned false.
  
−
==== GET /mco/client/outdated ====
+
If it returns false, this screen appears : [http://prntscr.com/ewxutq].
 +
 
 +
==== GET /mco/client/compatible ====
  
 
Returns whether the clients version is up to date with Realms. This is checked against the Cookie token.
 
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.
+
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 ====
 
==== GET /worlds ====
Line 113: Line 141:
 
Example:
 
Example:
 
   
 
   
−
  {"worlds": [
+
  {"servers":[{ 
−
    {"id": 1,
+
        "id":1,
−
    "remoteSubscriptionId": "1",
+
        "remoteSubscriptionId":"aaaa0000bbbb1111cccc2222dddd3333",
−
    "name": "A Test Server",
+
        "owner":"j_selby",
−
    "players": ["Notch"],
+
        "ownerUUID":"3333dddd2222cccc1111bbbb0000aaaa",
−
    "motd": "This is a testing server!",
+
        "name":"A Test Server",
−
    "state": "OPEN",
+
        "motd":"This is a testing server!",
−
    "owner": "j_selby",
+
        "state":"OPEN",
−
    "daysLeft": 30,
+
        "daysLeft":30,
−
    "ip": "localhost:25565",
+
        "expired":false,
−
    "expired": false,
+
        "expiredTrial":false,
−
    "minigame": false}, ...
+
        "worldType":"NORMAL",
−
  ]}
+
        "players":["Notch"],
 +
        "maxPlayers":10,
 +
        "minigameName":null,
 +
        "minigameId":null,
 +
        "minigameImage":null,
 +
        "activeSlot":1,
 +
        "slots":null,
 +
        "member":false
 +
      }]
 +
  }
  
 
==== GET /worlds/$ID ====
 
==== GET /worlds/$ID ====
  
 
Returns a single server listing about a server.
 
Returns a single server listing about a server.
−
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.
+
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.
 
Returns: a JSON encoded Server, as above.
  
−
==== GET /worlds/$ID/join ====
+
==== GET /worlds/v1/$ID/join/pc ====
 
Requires TOS to be agreed to (as below).
 
Requires TOS to be agreed to (as below).
  
Line 146: Line 183:
 
|-
 
|-
 
| address || The address of a server, encoded as [IP]:[Port] || String
 
| address || The address of a server, encoded as [IP]:[Port] || String
 +
|-
 +
| pendingUpdate || If the server is waiting to update to a newer version || Boolean
 
|}
 
|}
  
Line 155: Line 194:
  
 
Returns: a JSON encoded list of backups for the specified world ID
 
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 /worlds/$ID/slot/$WORLD(1-4)/download ====
Line 208: Line 266:
  
 
Returns: Integer value
 
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
 +
 +
{| class="wikitable"
 +
! Template !! In-game name !! Description
 +
|-
 +
| MINIGAME || Minigames || Minigames are self-contained, repeatable, often cooperative or competitive games within Minecraft.
 +
|-
 +
| ADVENTUREMAP || Adventures || Adventures are generally designed to be played from start to finish with a specific goal in mind. They often contain a story, an overarching objective, or an end goal for the player to strive towards.
 +
|-
 +
| EXPERIENCE || Experiences || Experiences are a category of loosely-defined maps mostly without a specific intended goal, where the player's purpose might be to explore, experience, or observe.
 +
|-
 +
| NORMAL || World templates || A world template is a custom survival world spawn where vanilla Minecraft terrain continues to generate outside of the custom area. They often allow the player to start with something extra compared to a regular survival world, such as a deserted temple, an abandoned outpost, or perhaps a mysterious sunken ruin.
 +
|-
 +
| INSPIRATION || Inspiration || Inspiration maps are generally designed to encourage and inspire players to create or design new things in Minecraft.
 +
|}
 +
Returns a json response like:
 +
 +
{
 +
    "templates": [
 +
        {
 +
            "id": 292,
 +
            "name": "Maze Wars",
 +
            "version": "1.0.3",
 +
            "author": "Azerus Team",
 +
            "link": "",
 +
            "image": "<base64 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 requests ===
 
=== POST requests ===
Line 213: Line 340:
 
==== POST /mco/tos/agreed ====
 
==== 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.
 
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 requests ===
 +
==== 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/backups?backupId=$BACKUP_ID ====
 +
Replaces the world of the realm with the specified backup.
 +
 +
'''Response'''
 +
 +
Either returns <code>Retry again later</code> or <code>true</code>. It seems to always return "Retry again later" on the first try.
 +
 +
==== 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 requests ===
 +
==== 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"
 +
    ]
 +
}

Latest revision as of 17:57, 3 May 2024

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 Bedrock Edition in development, located at https://pocket.realms.minecraft.net. It is being documented at Bedrock 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.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

Notes

As per standard HTTP, a GET request has no parameters, and a POST request can potentially contain content (Note, several POST requests below have 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
id The ID of the server. Must be unique Integer
remoteSubscriptionId Unknown, perhaps linked to transaction? Seems to work if same as 'id' String
owner The owner of the server. String
ownerUUID The unique ID of the owner. If this is equal to the previewing players unique ID, the configure button will be accessible. Note that the UUID haven't got hyphens String
name The name of the server String
motd The MOTD of the server. Does support color codes, but officially color cannot be set. String
state The status of the server. Can be one of the following: CLOSED, OPEN, UNINITIALIZED String
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
worldType Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION) String
players An array of currently connected players? JSON Array, with string values
maxPlayers The max players of the server, always returns '10' Integer
minigameName Name of minigame that is currently active. Returns `null` if not in a minigame String
minigameId Not confirmed, probably unique Id of Minigame map. Returns `null` if not in a minigame Integer
minigameImage base64 of the current minigame image in format PNG. Returns `null` if not in a minigame String
activeSlot Current server world (1-4) Integer
slots List of worlds slots. Only visible by owner (/worlds/$ID) Unknown
member Unknown Boolean
parentWorldId ID of the parent realm that a snapshot realm is tied to. Value of -1 on the parent realm Integer
parentWorldName Name of the parent realm that a snapshot realm is tied to String
compatibility Compatibility with the current game version. Can be one of the following: UNVERIFIABLE, INCOMPATIBLE, NEEDS_DOWNGRADE, NEEDS_UPGRADE, COMPATIBLE String
activeVersion Game version of the realm String

Environments

The environment defines the location of the API. The client supports switching between multiple different Realms environments, using an environment variable.

It can be set with -Drealms.environment=.

If not specified, the "PRODUCTION" environment is used.

Value API endpoint
PRODUCTION https://pc.realms.minecraft.net
STAGE https://pc-stage.realms.minecraft.net
LOCAL http://localhost:8080

When set to "STAGE" or "LOCAL", the text "STAGE!" in yellow or "LOCAL!" in light green is displayed on top of the Minecraft Realms logo in the Realms menu.

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.

If it returns false, this screen appears : [1].

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.

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

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:

Key Value Value Type
address The address of a server, encoded as [IP]:[Port] String
pendingUpdate If the server is waiting to update to a newer version Boolean

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:

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

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

Template In-game name Description
MINIGAME Minigames Minigames are self-contained, repeatable, often cooperative or competitive games within Minecraft.
ADVENTUREMAP Adventures Adventures are generally designed to be played from start to finish with a specific goal in mind. They often contain a story, an overarching objective, or an end goal for the player to strive towards.
EXPERIENCE Experiences Experiences are a category of loosely-defined maps mostly without a specific intended goal, where the player's purpose might be to explore, experience, or observe.
NORMAL World templates A world template is a custom survival world spawn where vanilla Minecraft terrain continues to generate outside of the custom area. They often allow the player to start with something extra compared to a regular survival world, such as a deserted temple, an abandoned outpost, or perhaps a mysterious sunken ruin.
INSPIRATION Inspiration Inspiration maps are generally designed to encourage and inspire players to create or design new things in Minecraft.

Returns a json response like: 

{
    "templates": [
        {
            "id": 292,
            "name": "Maze Wars",
            "version": "1.0.3",
            "author": "Azerus Team",
            "link": "",
            "image": "<base64 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 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.

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 requests

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/backups?backupId=$BACKUP_ID

Replaces the world of the realm with the specified backup.

Response

Either returns Retry again later or true. It seems to always return "Retry again later" on the first try.

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 requests

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"
    ]
}
Retrieved from "https://wiki.vg/index.php?title=Realms_API&oldid=19188"