Difference between revisions of "Bedrock Realms"

Revision as of 15:43, 14 September 2021

This page was created using information from Minecraft 1.10.1 on Windows 10. The process is (presumably) similar for Minecraft on Nintendo Switch, iOS, Android and Xbox One.

Edit: Recently updated with more endpoints available in the 1.17.1 release of Minecraft Bedrock Edition

The information on this page may be incorrect and incomplete.

Authentication

Login is handled by Xbox Live, which is out of scope of this page.

To authenticate with the endpoints, you need an Authorization header set with an XBL-3.0 Xbox Live service token.

Endpoints

Server hostname: https://pocket.realms.minecraft.net

GET /mco/client/compatible

Checks whether the current version is compatible with Minecraft Realms (usually reserved for the latest version). A `Client-Version` header must be set with the version of the game and a `User-Agent` header of the edition of the game. This is requested whenever the game is launched with an active internet connection and when logged in to Xbox Live.

This endpoint returns COMPATIBLE when the version is compatible, else it returns OUTDATED when the version is either outdated or a beta version is being used.

Request:

GET /mco/client/compatible HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:24:59 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 10
Connection: keep-alive

COMPATIBLE

GET /worlds

Gets a list of realms the current Xbox Live user has access to. This is requested on every tab change and load of the "Play" screen. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Response (as JSON)

servers - An array containing every realm object.
- id - The ID of the realm as an integer.
- remoteSubscriptionId - The subscription ID of the realm as a string. (unknown purpose)
- owner - This is always an empty string.
- ownerUUID - The XboxUserID (XUID) of the owner as a string.
- name - The name of the Realm as a string.
- motd - This is always an empty string. (unknown usage).
- defaultPermission - The default permission level of the Realm world. ("MEMBER" by default)
- state - The state of the realm as a string. ("OPEN" or "CLOSED")
- daysLeft - The days remaining before renewal of the Realm as an integer. (always 0 for Realms where the current user is not the owner)
- expired - A boolean value of whether the Realm is expired or not.
- expiredTrial - A boolean value of whether the Realm has expired as a trial or not.
- gracePeriod - A boolean value of whether the Realm is in its grace period after expiry or not.
- worldType - The world type of the currently loaded world ("NORMAL" by default)
- players - Always null. (TODO: is it?)
- maxPlayers - The maximum simultaneous player count of the Realm. (Integer, either 2 or 10)
- minigameName - Unused, always null.
- minigameId - Unused, always null.
- minigameImage - Unused, always null.
- activeSlot - The selected world slot from the realm, unused, always set to 1.
- slots - Unknown, always null.
- member - Unknown, always false. (even when member or owner)
- clubId - The ID of the associated Xbox Live club as an integer.

GET /worlds/{id}

Gets information about the Realm and world specified in the URL. Returns a 403 error if the current user is not the owner of the Realm. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Response (as JSON):

id - The ID of the realm as an integer.
remoteSubscriptionId - The subscription ID of the realm as a string. (unknown purpose)
owner - This is always an empty string.
ownerUUID - The XUID of the owner as a string.
name - The name of the Realm as a string.
motd - This is always an empty string. (unknown usage).
defaultPermission - The default permission level of the Realm world. ("MEMBER" by default)
state - The state of the realm as a string. ("OPEN" or "CLOSED")
daysLeft - The days remaining before renewal of the Realm as an integer. (always 0 for Realms where the current user is not the owner)
expired - A boolean value of whether the Realm is expired or not.
expiredTrial - A boolean value of whether the Realm has expired as a trial or not.
gracePeriod - A boolean value of whether the Realm is in its grace period after expiry or not.
worldType - The world type of the currently loaded world ("NORMAL" by default)
players - An array containing all of the players who have been invited to the Realm, minus the owner.
- uuid - The XUID of the player as a string.
- name - Unknown, always null in testing. (Could change once player joins, untested)
- operator - A boolean value of whether the player is an operator of the Realm or not.
- accepted - A boolean value of whether the player has accepted the pending invite request.
- online - A boolean value of whether the player is online on the realm.
- permission - The permission value of the player as a string. ("MEMBER" by default)
maxPlayers - The maximum simultaneous player count of the Realm. (Integer, either 2 or 10)
minigameName - Unused, always null.
minigameId - Unused, always null.
minigameImage - Unused, always null.
activeSlot - The selected world slot from the Realm, unused, always set to 1.
slots - An array containing information on all the slots on the Realm.
- options - A string containing JSON information on the world. (TODO: document data on this)
member - Unknown, always false. (even when member or owner)
clubId - The ID of the associated Xbox Live club as an integer.

GET /server/{id}/join

Gets the IP address and port of the Realm dedicated server specified in the URL. This is requested whenever the game attempts to load a Realm. Returns 403 if the current user doesn't have permission for that Realm. A `Client-Version` header and a `User-Agent` header must be sent with the request, however this is not verified.

Request:

GET https://pocket.realms.minecraft.net/worlds/[REALMID]/join HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.8.2
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 08 Apr 2019 00:02:05 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 91
Connection: keep-alive

{"address":"[server address on amazonaws.com]:[realm port]","pendingUpdate":true}

GET /invites/count/pending

Gets the amount of pending Realm invites of the currently logged in Xbox Live user. The game periodically requests this while on the main menu of the game. The response is returned as an integer. A `Client-Version` header and a `User-Agent` header must be sent with the request, however, this is not verified.

Request:

GET /invites/count/pending HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:52:15 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 1
Connection: keep-alive

0

GET /world/{id}/content

Gets ids of the Realms listed resource packs and behaviour packs.

Request:

GET /world/[REALMID]/content HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response:

{
   "worldId": Integer,
   "name": String,
   "resourcePacks": [
       {
           "packId": String,
           "version": String
       },
       {
           "packId": String,
           "version": String
       }
   ],
   "behaviorPacks": [
       {
           "packId": String,
           "version": String
       }
   ]
}

GET /subscriptions/{id}/details

Gets the details of the subscription for a Realm such as total time left and renewal date

Request:

GET /subscriptions/[REALMID]/details HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response:

{
   "type": "SUBSCRIPTION",
   "store": "xbox1.store",
   "startDate": 1623908801932,
   "endDate": 1626428175000,
   "renewalPeriod": 30,
   "daysLeft": 2,
   "subscriptionId": String
}

GET /worlds/{id}/backups

Gets an array of backups which includes metadata about the backup as well as the id which you can then use to download or replace a world with a backup.

Request:

GET /worlds/[REALMID]/backups HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

{
 "backups": [
   {
     "backupId": "2021-07-13T18:30:41.7172714Z",
     "lastModifiedDate": 1626201041000,
     "size": 35211208,
     "metadata": {
       "game_difficulty": "3",
       "name": "Test Realm",
       "game_server_version": "1.17.1",
       "enabled_packs": {
         "resourcePacks": [],
         "behaviorPacks": []
       },
       "description": null,
       "game_mode": "2",
       "world_type": "NORMAL"
     }
   }
 ]
}

GET /archive/download/world/{id}/1/{backupId}

Gets information about a backup including its download Url and token which you can then use to download the world file.

Request:

GET /archive/download/world/[REALMID]/1/[BACKUPID] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

{
   "downloadUrl": "https://archive-pocket-production-eu-west-1.realms.minecraft.net/worlds",
   "token": AUTH_TOKEN,
   "size": 31885490
}

GET /archive/download/world/{id}/1/latest

Gets information about the latest backup including its download Url and token which you can then use to download the world file.

Request:

GET /archive/download/world/[REALMID]/1/latest HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

{
   "downloadUrl": "https://archive-pocket-production-eu-west-1.realms.minecraft.net/worlds",
   "token": AUTH_TOKEN,
   "size": 31885490
}

GET /links/v1?worldId={id}

Gets the invite links for a Realm.

Request:

GET /links/v1?worldId=[REALMID] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

[
 {
   "linkId": String,
   "profileUuid": String,
   "type": "INFINITE",
   "ts": 1617994099284,
   "url": "https://realms.gg/[LINKID]",
   "deepLinkUrl": "minecraft://acceptRealmInvite?inviteID=[LINKID]"
 }
]

GET /trial/new

Returns whether the account is eligible for a free Realm trial. Returns 403 if already redeemed.

Request:

GET /trial/new HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

Unknown

GET /worlds/v1/link/{realmInviteCode}

Gets information about the Realm and world which belongs to the invite code.

Request:

GET /worlds/v1/link/[realmInviteCode] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

Same as GET /worlds/{id} endpoint

GET /activities/live/players

Gets an array of Realms that are on the user's server list with information about which players are currently in the Realm. Often returns an empty array even though Realms have players in them

Request:

GET /activities/live/players HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

{
 "servers": [
   {
     "id": REALM_ID,
     "players": [
       {
         "uuid": PLAYER_XUID,
         "name": null,
         "operator": false,
         "accepted": true,
         "online": true,
         "permission": "MEMBER"
       },
       {
         "uuid": PLAYER_XUID,
         "name": null,
         "operator": false,
         "accepted": true,
         "online": true,
         "permission": "MEMBER"
       }
     ],
     "full": false
   }
 ]
}

GET /worlds/{id}/blocklist

Gets an array of XUIDs of all the banned players of that Realm

Request:

GET /worlds/[REALMID]/blocklist HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

[
  "XUID1",
  "XUID2"
]

POST /worlds/{id}/blocklist/{xuid]

Include a users XUID in the POST URL and they will be added to the blocklist for that Realm.

Request:

POST /worlds/[REALMID]/blocklist/[XUID] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Reponse

204 No Content

POST /invites/v1/link/accept/{realmInviteCode}

Include the Realms invite code in the POST URL to add the Realm to your server list

Request:

POST /invites/v1/link/accept/[realmInviteCode] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Reponse

Same as GET /worlds/{id} endpoint

POST /worlds/{id}/configuration

Update a Realms configuration. Change any field in the body and it'll update after making the POST request. Note I've only tested the description and name.

Request:

POST /worlds/[REALMID]/configuration HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Body

{
 "description": {
   "description": "Test description",
   "name": "Test Realm"
 },
 "options": {
   "adventureMap": false,
   "cheatsAllowed": false,
   "commandBlocks": false,
   "customGameServerGlobalProperties": null,
   "difficulty": 3,
   "enabledPacks": {
     "behaviorPacks": [],
     "resourcePacks": []
   },
   "forceGameMode": false,
   "gameMode": 0,
   "incompatibilities": [],
   "pvp": true,
   "resourcePackHash": null,
   "slotName": "My World",
   "spawnAnimals": true,
   "spawnMonsters": true,
   "spawnNPCs": true,
   "spawnProtection": 0,
   "texturePacksRequired": false,
   "timeRequest": null,
   "versionLock": true,
   "versionRef": "5a7c1bcb9b95ebce0b42e7684a0c8f95f0e0c9d0",
   "worldSettings": {},
   "worldTemplateId": -1,
   "worldTemplateImage": null
 }
}

Response

wip

PUT /invites/{id}/invite/update

Depending on the parameter passed you can invite someone to the Realm or remove them from the realm. Note this isn't like banning a player it removes the selected Realm from their server list and kicks them if they are logged in.

Request:

PUT /invites/[REALMID]/invite/update HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Body

{
 "invites": {
   "PLAYER_XUID": "ADD" || "REMOVE"
 }
}

Response

Same as GET /worlds/{id} endpoint

PUT /worlds/{id}/defaultPermission

Changes the default user permission within that realm. Options are VISITOR, MEMBER or OPERATOR

Request:

PUT /worlds/[REALMID]/defaultPermission HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Body

{
 "permission": "VISITOR" || "MEMBER" || "OPERATOR"
}

Response

Returns 204 No Content

PUT /worlds/{id}/userPermission

Changes a players permission within that realm. Options are VISITOR, MEMBER or OPERATOR

Request:

PUT /worlds/[REALMID]/userPermission HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Body

{
 "permission": "VISITOR" || "MEMBER" || "OPERATOR"
 "xuid":"PLAYER_XUID"
}

Response

Returns 204 No Content

PUT /worlds/{id}/backups?backupId={backupId}&clientSupportsRetries

Replaces the world of the realm with a backup. Note from testing, it seems you have to call this request twice for it to function, the first request always seems to 503 error.

Request:

PUT /worlds/{id}/backups?backupId={backupId}&clientSupportsRetries HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

wip

PUT /worlds/{id}/slot/{slotNum}

Replaces the active world within a Realm. Slot number can be 1, 2 or 3.

Request:

PUT /worlds/{id}/slot/{slotNum} HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

true

PUT /worlds/{id}/open

Opens the specified Realm to all invited users and allows connections. Returns 403 if the current user is not the owner of the Realm. The response is true if the action is successful, and false otherwise. A `Client-Version` header and a `User-Agent` header must be sent with the request, however, this is not verified.

Request:

PUT /worlds/[REALMID]/open HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Content-Length: 0
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:52:15 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 1
Connection: keep-alive

true

PUT /worlds/{id}/close

Closes the specified Realm and disables all new connections to the server. Returns 403 if the current user is not the owner of the Realm. The response is true if the action is successful, and false otherwise. A `Client-Version` header and a `User-Agent` header must be sent with the request, however, this is not verified.

Request:

PUT /worlds/[REALMID]/close HTTP/1.1
Accept: */*
Authorization: XBL3.0 [SERVICETOKEN]
Cache-Control: no-cache
Charset: utf-8
Client-Version: 1.10.1
User-Agent: MCPE/UWP
Accept-Language: en-GB
Accept-Encoding: gzip, deflate, br
Host: pocket.realms.minecraft.net
Content-Length: 0
Connection: Keep-Alive

Response:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Sun, 07 Apr 2019 23:52:15 GMT
X-REQUEST-ID: [REQUESTID]
Content-Length: 1
Connection: keep-alive

true

DELETE /worlds/{id}/blocklist/{xuid}

Include a users XUID in the POST URL and they will be removed from the blocklist for that Realm.

Request:

DELETE /worlds/[REALMID]/blocklist/[XUID] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

Returns 204 No Content

DELETE /invites/{id}

Removes the specified realm from your joinable realms list.

Request:

DELETE /invites/[REALMID] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

Returns 204 No Content

DELETE /worlds/{id}

Deletes a Realm completely.

Request:

DELETE /worlds/[REALMID] HTTP/1.1  
Accept: */*  
authorization: XBL3.0 [SERVICETOKEN]
client-version: 1.17.10   
user-agent: MCPE/UWP  
Accept-Language: en-GB,en
Accept-Encoding: gzip, deflate, be  
Host: pocket.realms.minecraft.net

Response

Returns 204 No Content

@@ Line 443: / Line 443: @@
 No Content
-=== POST /worlds/v1/link/accept/{realmInviteCode} ===
+=== POST /invites/v1/link/accept/{realmInviteCode} ===
 Include the Realms invite code in the POST URL to add the Realm to your server list
 '''Request:'''
-  POST /worlds/v1/link/accept/[realmInviteCode] HTTP/1.1
+  POST /invites/v1/link/accept/[realmInviteCode] HTTP/1.1
   Accept: */*
   authorization: XBL3.0 [SERVICETOKEN]

Difference between revisions of "Bedrock Realms"

Revision as of 15:43, 14 September 2021

Contents

Authentication

Endpoints

GET /mco/client/compatible

GET /worlds

GET /worlds/{id}

GET /server/{id}/join

GET /invites/count/pending

GET /world/{id}/content

GET /subscriptions/{id}/details

GET /worlds/{id}/backups

GET /archive/download/world/{id}/1/{backupId}

GET /archive/download/world/{id}/1/latest

GET /links/v1?worldId={id}

GET /trial/new

GET /worlds/v1/link/{realmInviteCode}

GET /activities/live/players

GET /worlds/{id}/blocklist

POST /worlds/{id}/blocklist/{xuid]

POST /invites/v1/link/accept/{realmInviteCode}

POST /worlds/{id}/configuration

PUT /invites/{id}/invite/update

PUT /worlds/{id}/defaultPermission

PUT /worlds/{id}/userPermission

PUT /worlds/{id}/backups?backupId={backupId}&clientSupportsRetries

PUT /worlds/{id}/slot/{slotNum}

PUT /worlds/{id}/open

PUT /worlds/{id}/close

DELETE /worlds/{id}/blocklist/{xuid}

DELETE /invites/{id}

DELETE /worlds/{id}

Navigation menu

Search