Difference between revisions of "Realms API"
(14 intermediate revisions by 5 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://pc.realms.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 | + | 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 26: | 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. | + | Cookie: sid=<token>;user=Herobrine;version=1.14.4 |
Cache-Control: no-cache | Cache-Control: no-cache | ||
Pragma: no-cache | Pragma: no-cache | ||
Line 35: | Line 33: | ||
== 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 | + | 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 52: | Line 50: | ||
| name || The name of the server || String | | name || The name of the server || String | ||
|- | |- | ||
− | | motd || The MOTD of the server. | + | | 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: | + | | 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 64: | Line 62: | ||
| worldType || Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION)|| String | | worldType || Type of the world. Can be NORMAL, MINIGAME, ADVENTUREMAP, EXPERIENCE, INSPIRATION)|| String | ||
|- | |- | ||
− | | players || | + | | 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 | ||
Line 79: | Line 77: | ||
|- | |- | ||
| member || Unknown || Boolean | | 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 <code>-Drealms.environment=</code>. | ||
+ | |||
+ | If not specified, the "PRODUCTION" environment is used. | ||
+ | |||
+ | {| class="wikitable" | ||
+ | ! 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 == | == Endpoints == | ||
Line 169: | 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 296: | 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 ==== | + | ==== POST /ops/$WORLD_ID/$UUID ==== |
Give operator status for player by uuid | Give operator status for player by uuid | ||
Line 369: | Line 413: | ||
Send empty message if successful | 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 requests === | ||
Line 376: | Line 436: | ||
Returns empty message if success | Returns empty message if success | ||
− | ==== DELETE ops/$WORLD_ID/$UUID ==== | + | ==== DELETE /ops/$WORLD_ID/$UUID ==== |
Remove operator status for player by uuid | Remove operator status for player by uuid | ||
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
Contents
- 1 Sessions
- 2 Notes
- 3 Defining a server
- 4 Environments
- 5 Endpoints
- 5.1 GET requests
- 5.1.1 GET /mco/available
- 5.1.2 GET /mco/client/compatible
- 5.1.3 GET /worlds
- 5.1.4 GET /worlds/$ID
- 5.1.5 GET /worlds/v1/$ID/join/pc
- 5.1.6 GET /worlds/$ID/backups
- 5.1.7 GET /worlds/$ID/slot/$WORLD(1-4)/download
- 5.1.8 GET /ops/$ID
- 5.1.9 GET /subscriptions/$ID
- 5.1.10 GET /mco/buy
- 5.1.11 GET /invites/count/pending
- 5.1.12 GET /invites/pending
- 5.1.13 GET /worlds/templates/$TEMPLATE?page=$PAGE&pageSize=$PAGE_SIZE
- 5.1.14 GET /trial
- 5.1.15 GET /activities/liveplayerlist
- 5.1.16 GET /subscriptions/$WORLD_ID
- 5.2 POST requests
- 5.3 PUT requests
- 5.4 DELETE requests
- 5.1 GET requests
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" ] }