Minecraft:Bedrock Realms API

Template:Exclusive Template:WIP

The Bedrock Realms API is the HTTP interface used to list, join, and manage Minecraft:Realms in Template:BE. It uses Xbox Live authentication and is separate from the game protocol used after connecting to a Realm.

Authentication

The Bedrock Realms API uses an Xbox Live XSTS token issued for the relying party https://pocket.realms.minecraft.net/, including its trailing slash.

The authorization header contains the Xbox user hash and the XSTS token, separated by a semicolon. The hash is not the player's XUID.

<syntaxhighlight lang="http"> Authorization: XBL3.0 x=<user-hash>;<XSTS-token> </syntaxhighlight>

For the token acquisition process, see Minecraft:Microsoft authentication.

Service hosts

Host	Description
`https://pocket.realms.minecraft.net`	Bedrock Realms API endpoint.
`https://bedrock.frontendlegacy.realms.minecraft-services.net`	Bedrock Realms API host.
`https://frontend.realms.minecraft-services.net`	Realms service frontend.
`https://bedrock.frontend.realms.minecraft-services.net`	Bedrock Realms service frontend.

Request format

Endpoint paths are relative to the service host. For example, /worlds becomes https://pocket.realms.minecraft.net/worlds. Requests use the following headers:

Header	Description
`Authorization`	Xbox Live user hash and XSTS token in the `XBL3.0` format.
`Client-Version`	Client's game version.
`User-Agent`	Client identifier, such as `MCPE/UWP`.
`Accept`	Accepted response content types, such as `application/json`.
`Content-Type`	`application/json` for a JSON request body.
`is-prerelease`	Optional flag set to `true` for Preview Realms.

<syntaxhighlight lang="http"> GET /worlds HTTP/1.1 Host: pocket.realms.minecraft.net Authorization: XBL3.0 x=<user-hash>;<XSTS-token> Client-Version: 1.26.52 User-Agent: MCPE/UWP Accept: application/json </syntaxhighlight>

Minecraft service discovery returns service environments through https://client.discovery.minecraft-services.net/api/v1.0/discovery/MinecraftPE/builds/1.26.52.

Endpoints

Shared response objects are described at Minecraft:Bedrock Realms API/Responses. Response examples use placeholder values and may omit fields.

In paths, {id} is a Realm ID, {xuid} is an Xbox user ID, and {slotId} is a world slot number. An invite code identifies a Realm invitation link; an invitation ID identifies a pending invitation.

GET /mco/client/compatible

Checks whether the supplied client version is accepted by Realms.

Responses

200 OK

Plain text: COMPATIBLE or OUTDATED.

<syntaxhighlight lang="text"> COMPATIBLE </syntaxhighlight>

GET /worlds

Lists the Realms the authenticated account owns or has joined.

Responses

200 OK

A JSON object containing servers, an array of Realm objects.

Example response:

<syntaxhighlight lang="json"> {

 "servers": [
   {
     "id": 123456,
     "ownerUUID": "2530000000000000",
     "name": "Example Realm",
     "motd": "Example description",
     "state": "OPEN",
     "players": null,
     "maxPlayers": 10,
     "activeSlot": 1
   }
 ]

} </syntaxhighlight>

GET /worlds/{id}

Returns details about a Realm, its members, and its world slots.

Responses

200 OK

A Realm object.

Example response:

<syntaxhighlight lang="json"> {

 "id": 123456,
 "ownerUUID": "2530000000000000",
 "name": "Example Realm",
 "motd": "Example description",
 "state": "OPEN",
 "players": [
   {
     "uuid": "2530000000000001",
     "name": null,
     "operator": false,
     "accepted": true,
     "online": true,
     "permission": "MEMBER"
   }
 ],
 "maxPlayers": 10,
 "activeSlot": 1

} </syntaxhighlight>

GET /worlds/{id}/join

Returns the connection address and network protocol used to join a Realm.

Returns the following fields:

Field	Type	Description
`address`	String	Connection address; its interpretation depends on `networkProtocol`.
`networkProtocol`	String	Transport or signaling protocol identifier.
`pendingUpdate`	Boolean	Whether an update is pending.
`sessionRegionData`	Object	Region data containing `regionName` and `serviceQuality`.

The networkProtocol value determines how to interpret address:

Protocol	Address interpretation
`DEFAULT`	A host and port for a Minecraft:RakNet connection.
`NETHERNET`	A Minecraft:NetherNet peer address.
`NETHERNET_JSONRPC`	A Minecraft:NetherNet peer address using the JSON-RPC signaling variant.

Responses

200 OK

JSON connection information.

Example response:

<syntaxhighlight lang="json"> {

 "networkProtocol": "NETHERNET",
 "address": "00000000-0000-4000-8000-000000000000",
 "pendingUpdate": false,
 "sessionRegionData": {
   "regionName": "example-region",
   "serviceQuality": 0
 }

} </syntaxhighlight>

403 Forbidden

The account does not have permission to join the Realm.

404 Not Found

The requested Realm could not be found.

503 Service Unavailable

The Realm is starting or temporarily unavailable.

GET /invites/count/pending

Returns the number of pending invitations for the authenticated account.

Responses

200 OK

A count returned as text, for example 0.

GET /invites/pending

Lists the account's pending invitations.

Responses

200 OK

An object containing an invites array. Entries include invitationId, worldName, worldDescription, worldOwnerName, worldOwnerUuid, and date.

Example response:

<syntaxhighlight lang="json"> {

 "invites": [
   {
     "invitationId": "12345",
     "worldName": "Example Realm",
     "worldDescription": "Example description",
     "worldOwnerName": null,
     "worldOwnerUuid": "2530000000000000",
     "date": 1700000000000
   }
 ]

} </syntaxhighlight>

GET /world/{id}/content

Returns information about the world's resource packs and behavior packs.

Responses

200 OK

An object containing worldId, name, resourcePacks, and behaviorPacks. Pack entries contain packId and version.

Example response:

<syntaxhighlight lang="json"> {

 "worldId": 123456,
 "name": "Example Realm",
 "resourcePacks": [],
 "behaviorPacks": [
   {
     "packId": "00000000-0000-4000-8000-000000000000",
     "version": "1.0.0"
   }
 ]

} </syntaxhighlight>

GET /subscriptions/{id}

Returns basic subscription information for a Realm.

Responses

200 OK

An object including startDate, daysLeft, and subscriptionType.

Example response:

<syntaxhighlight lang="json"> {

 "startDate": 1700000000000,
 "daysLeft": 2,
 "subscriptionType": "RECURRING"

} </syntaxhighlight>

GET /subscriptions/{id}/details

Returns detailed subscription information, including the store and renewal period.

Responses

200 OK

An object including type, store, startDate, endDate, renewalPeriod, daysLeft, and subscriptionId. The date fields are Unix timestamps in milliseconds.

Example response:

<syntaxhighlight lang="json"> {

 "type": "SUBSCRIPTION",
 "store": "xbox1.store",
 "startDate": 1623908801932,
 "endDate": 1626428175000,
 "renewalPeriod": 30,
 "daysLeft": 2,
 "subscriptionId": "example-subscription"

} </syntaxhighlight>

GET /worlds/{id}/backups

Lists the available world backups.

Responses

200 OK

An object containing a backups array of backup objects.

Example response:

<syntaxhighlight lang="json"> {

 "backups": [
   {
     "backupId": "2026-10-01T12:00:00.000Z",
     "lastModifiedDate": 1790856000000,
     "size": 10000,
     "metadata": {
       "name": "Example Realm",
       "game_difficulty": "2",
       "game_mode": "0",
       "world_type": "NORMAL"
     }
   }
 ]

} </syntaxhighlight>

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

Returns the information required to download a specified backup.

Responses

200 OK

A download object. The slotId parameter identifies the world slot to download.

Example response:

<syntaxhighlight lang="json"> {

 "downloadUrl": "https://example.invalid/worlds",
 "token": "<download-token>",
 "size": 10000

} </syntaxhighlight>

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

Returns download information for the current world in the selected slot.

Responses

200 OK

A download object. The value latest requests the current world rather than the newest saved backup.

Example response:

<syntaxhighlight lang="json"> {

 "downloadUrl": "https://example.invalid/worlds",
 "token": "<download-token>",
 "size": 10000

} </syntaxhighlight>

GET /links/v1?worldId={id}

Lists the invite links associated with a Realm.

Responses

200 OK

An array of invite link objects.

Example response:

<syntaxhighlight lang="json"> [

 {
   "linkId": "ExampleCode",
   "profileUuid": "2530000000000000",
   "type": "INFINITE",
   "ts": 1700000000000,
   "url": "https://realms.gg/ExampleCode",
   "deepLinkUrl": "minecraft://acceptRealmInvite?inviteID=ExampleCode"
 }

] </syntaxhighlight>

GET /trial/new

Checks eligibility for a Realm trial.

Responses

Success response

The success status and response body are not documented here.

403 Forbidden

A trial is not available for the account.

<syntaxhighlight lang="json"> {

 "errorCode": 403,
 "errorMsg": "Trial is not available"

} </syntaxhighlight>

GET /worlds/v1/link/{realmInviteCode}

Looks up Realm information using an invite code.

Responses

200 OK

A Realm object. Looking up an invite code does not accept the invitation.

Example response:

<syntaxhighlight lang="json"> {

 "id": 123456,
 "ownerUUID": "2530000000000000",
 "name": "Example Realm",
 "motd": "Example description",
 "state": "OPEN",
 "players": null,
 "maxPlayers": 10,
 "activeSlot": 1

} </syntaxhighlight>

GET /activities/live/players

Returns player-activity information for Realms visible to the account.

Responses

200 OK

An object containing servers. Each entry can include a Realm id, players, and full. Results can be empty even when players are connected.

Example response:

<syntaxhighlight lang="json"> {

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

} </syntaxhighlight>

GET /worlds/{id}/blocklist

Lists the XUIDs blocked from a Realm.

Responses

200 OK

An array of XUID strings.

Example response:

<syntaxhighlight lang="json"> [

 "2530000000000001"

] </syntaxhighlight>

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

Adds a player to the Realm's blocklist.

Responses

204 No Content

No response body.

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

Accepts an invite code and adds the Realm to the account's joined list.

Responses

200 OK

A Realm object.

Example response:

<syntaxhighlight lang="json"> {

 "id": 123456,
 "ownerUUID": "2530000000000000",
 "name": "Example Realm",
 "motd": "Example description",
 "state": "OPEN",
 "players": null,
 "maxPlayers": 10,
 "activeSlot": 1

} </syntaxhighlight>

POST /worlds/{id}

Updates the Realm's name and description.

Request body:

<syntaxhighlight lang="json"> {

 "name": "Example Realm",
 "description": "Example description"

} </syntaxhighlight>

Responses

204 No Content

No response body.

POST /worlds/{id}/configuration

Updates the Realm's description and world configuration.

The description object contains the Realm name and description. The options object contains world settings. The following example shows a configuration excerpt.

Request body:

<syntaxhighlight lang="json"> {

 "description": {
   "name": "Example Realm",
   "description": "Example description"
 },
 "options": {
   "slotName": "Example world",
   "gameMode": 0,
   "difficulty": 2,
   "pvp": true,
   "texturePacksRequired": false
 }

} </syntaxhighlight>

Other configuration fields include cheatsAllowed, forceGameMode, enabledPacks, and worldSettings. The shape and supported options depend on the service version.

Responses

204 No Content

No response body.

POST /links/v1

Creates a Realm invite link.

Request body:

<syntaxhighlight lang="json"> {

 "type": "INFINITE",
 "worldId": 123456

} </syntaxhighlight>

Responses

200 OK

An invite link object.

Example response:

<syntaxhighlight lang="json"> {

 "linkId": "ExampleCode",
 "profileUuid": "2530000000000000",
 "type": "INFINITE",
 "ts": 1700000000000,
 "url": "https://realms.gg/ExampleCode",
 "deepLinkUrl": "minecraft://acceptRealmInvite?inviteID=ExampleCode"

} </syntaxhighlight>

PUT /invites/{id}/invite/update

Adds or removes Realm members, or changes their operator status.

Request body:

<syntaxhighlight lang="json"> {

 "invites": {
   "2530000000000000": "ADD"
 }

} </syntaxhighlight>

Action values include ADD, REMOVE, OP, and DEOP. Removing an invitation is distinct from adding the player to the blocklist.

Responses

200 OK

A Realm object.

Example response:

<syntaxhighlight lang="json"> {

 "id": 123456,
 "ownerUUID": "2530000000000000",
 "name": "Example Realm",
 "motd": "Example description",
 "state": "OPEN",
 "players": [
   {
     "uuid": "2530000000000001",
     "name": null,
     "operator": false,
     "accepted": true,
     "online": true,
     "permission": "MEMBER"
   }
 ],
 "maxPlayers": 10,
 "activeSlot": 1

} </syntaxhighlight>

PUT /invites/accept/{invitationId}

Accepts a pending invitation identified by its invitation ID.

Responses

204 No Content

No response body.

PUT /invites/reject/{invitationId}

Rejects a pending invitation identified by its invitation ID.

Responses

204 No Content

No response body.

PUT /world/{id}/defaultPermission

Changes the Realm's default player permission.

Request body:

<syntaxhighlight lang="json"> {

 "permission": "MEMBER"

} </syntaxhighlight>

Permission values are VISITOR, MEMBER, and OPERATOR.

Responses

204 No Content

No response body.

PUT /world/{id}/userPermission

Changes a specified player's permission in the Realm.

Request body:

<syntaxhighlight lang="json"> {

 "permission": "VISITOR",
 "xuid": "2530000000000000"

} </syntaxhighlight>

Responses

204 No Content

No response body.

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

Template:Update

Restores a saved backup to the Realm.

The backup ID is URL-encoded. The clientSupportsRetries query parameter is sent without a value.

Responses

Success response

The response can contain true. The success status remains unverified.

503 Service Unavailable

The restore cannot be completed yet.

<syntaxhighlight lang="text"> Retry again later </syntaxhighlight>

PUT /worlds/{id}/slot/{slotId}

Selects the active world slot.

World slots are numbered 1, 2, and 3. Selecting a slot is distinct from uploading or replacing its world.

Responses

200 OK

Response body:

PUT /worlds/{id}/open

Opens the Realm to players allowed to join.

Responses

200 OK

Plain text: true.

403 Forbidden

The account does not have permission to perform this operation.

503 Service Unavailable

The operation cannot be completed yet.

<syntaxhighlight lang="text"> Retry again later </syntaxhighlight>

PUT /worlds/{id}/close

Closes the Realm to player connections.

Responses

200 OK

Plain text: true.

403 Forbidden

The account does not have permission to perform this operation.

503 Service Unavailable

The operation cannot be completed yet.

<syntaxhighlight lang="text"> Retry again later </syntaxhighlight>

PUT /worlds/{id}/reset

Requests a reset of the Realm's world.

Responses

200 OK

Response body:

PUT /world/{id}/content/texturePacksRequired

Requires joining players to accept the Realm's resource packs.

Responses

204 No Content

No response body.

DELETE /world/{id}/content/texturePacksRequired

Template:Update

Removes the requirement to accept the Realm's resource packs.

Responses

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

Removes a player from the Realm's blocklist.

Responses

204 No Content

No response body.

DELETE /invites/{id}

Removes a Realm from the account's joined list.

This operation does not delete the owner's Realm.

Responses

204 No Content

No response body.

DELETE /worlds/{id}

Deletes a Realm.

Responses

204 No Content

No response body.

Stories endpoints

These endpoints manage Realm Stories and related activity. The /api/v1.0/ routes below use https://bedrock.frontend.realms.minecraft-services.net and return JSON. The settings endpoint uses the host specified in its description.

Template:WIP

Errors

Error statuses are listed under the applicable endpoint. An error body may be JSON or plain text; the HTTP status alone does not determine its format. For example, an unavailable trial returns a JSON object with errorCode and errorMsg, while some temporarily unavailable operations return the text Retry again later.

Template:Navbox Bedrock Edition