SyncBot: Sync: new page from Minecraft

2026-10-20T11:04:57Z

Sync: new page from Minecraft

New page

{{exclusive|bedrock}}
{{WIP}}

The '''Bedrock Realms API''' is the [[Minecraft:wikipedia:HTTP|HTTP]] interface used to list, join, and manage [[Minecraft:Realms]] in {{BE}}. It uses Xbox Live authentication and is separate from the [[Minecraft:Bedrock Edition protocol|game protocol]] used after connecting to a Realm.

== Authentication ==

The Bedrock Realms API uses an Xbox Live XSTS token issued for the relying party <code>https://pocket.realms.minecraft.net/</code>, 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 ==

{| class="wikitable"
! scope="col" | Host
! scope="col" | Description
|-
! scope="row" style="text-align: left;" | <code>https://pocket.realms.minecraft.net</code>
| Bedrock Realms API endpoint.
|-
! scope="row" style="text-align: left;" | <code>https://bedrock.frontendlegacy.realms.minecraft-services.net</code>
| Bedrock Realms API host.
|-
! scope="row" style="text-align: left;" | <code>https://frontend.realms.minecraft-services.net</code>
| Realms service frontend.
|-
! scope="row" style="text-align: left;" | <code>https://bedrock.frontend.realms.minecraft-services.net</code>
| Bedrock Realms service frontend.
|}

== Request format ==

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

{| class="wikitable"
! scope="col" | Header
! scope="col" | Description
|-
! scope="row" | <code>Authorization</code>
| Xbox Live user hash and XSTS token in the <code>XBL3.0</code> format.
|-
! scope="row" | <code>Client-Version</code>
| Client's game version.
|-
! scope="row" | <code>User-Agent</code>
| Client identifier, such as <code>MCPE/UWP</code>.
|-
! scope="row" | <code>Accept</code>
| Accepted response content types, such as <code>application/json</code>.
|-
! scope="row" | <code>Content-Type</code>
| <code>application/json</code> for a JSON request body.
|-
! scope="row" | <code>is-prerelease</code>
| Optional flag set to <code>true</code> 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 <code>https://client.discovery.minecraft-services.net/api/v1.0/discovery/MinecraftPE/builds/1.26.52</code>.

== Endpoints ==

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

In paths, <code>{id}</code> is a Realm ID, <code>{xuid}</code> is an Xbox user ID, and <code>{slotId}</code> 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: <code>COMPATIBLE</code> or <code>OUTDATED</code>.

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

=== GET /worlds ===

Lists the Realms the authenticated account owns or has joined.

==== Responses ====

'''200 OK'''

A JSON object containing <code>servers</code>, an array of [[Minecraft:Bedrock Realms API/Responses#Realm object|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 [[Minecraft:Bedrock Realms API/Responses#Realm object|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:

{| class="wikitable"
! scope="col" | Field
! scope="col" | Type
! scope="col" | Description
|-
! scope="row" | <code>address</code>
| String
| Connection address; its interpretation depends on <code>networkProtocol</code>.
|-
! scope="row" | <code>networkProtocol</code>
| String
| Transport or signaling protocol identifier.
|-
! scope="row" | <code>pendingUpdate</code>
| Boolean
| Whether an update is pending.
|-
! scope="row" | <code>sessionRegionData</code>
| Object
| Region data containing <code>regionName</code> and <code>serviceQuality</code>.
|}

The <code>networkProtocol</code> value determines how to interpret <code>address</code>:

{| class="wikitable"
! scope="col" | Protocol
! scope="col" | Address interpretation
|-
! scope="row" | <code>DEFAULT</code>
| A host and port for a [[Minecraft:RakNet]] connection.
|-
! scope="row" | <code>NETHERNET</code>
| A [[Minecraft:NetherNet]] peer address.
|-
! scope="row" | <code>NETHERNET_JSONRPC</code>
| A [[Minecraft:NetherNet]] peer address using the [[Minecraft:wikipedia:JSON-RPC|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 <code>0</code>.

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

=== GET /invites/pending ===

Lists the account's pending invitations.

==== Responses ====

'''200 OK'''

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

'''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 <code>worldId</code>, <code>name</code>, <code>resourcePacks</code>, and <code>behaviorPacks</code>. Pack entries contain <code>packId</code> and <code>version</code>.

'''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 <code>startDate</code>, <code>daysLeft</code>, and <code>subscriptionType</code>.

'''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 <code>type</code>, <code>store</code>, <code>startDate</code>, <code>endDate</code>, <code>renewalPeriod</code>, <code>daysLeft</code>, and <code>subscriptionId</code>. 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 <code>backups</code> array of [[Minecraft:Bedrock Realms API/Responses#Backup object|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 [[Minecraft:Bedrock Realms API/Responses#Download object|download object]]. The <code>slotId</code> 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 [[Minecraft:Bedrock Realms API/Responses#Download object|download object]]. The value <code>latest</code> 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 [[Minecraft:Bedrock Realms API/Responses#Invite link object|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 [[Minecraft:Bedrock Realms API/Responses#Realm object|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 <code>servers</code>. Each entry can include a Realm <code>id</code>, <code>players</code>, and <code>full</code>. 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 [[Minecraft:Bedrock Realms API/Responses#Realm object|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 <code>description</code> object contains the Realm name and description. The <code>options</code> 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 <code>cheatsAllowed</code>, <code>forceGameMode</code>, <code>enabledPacks</code>, and <code>worldSettings</code>. 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 [[Minecraft:Bedrock Realms API/Responses#Invite link object|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 <code>ADD</code>, <code>REMOVE</code>, <code>OP</code>, and <code>DEOP</code>. Removing an invitation is distinct from adding the player to the blocklist.

==== Responses ====

'''200 OK'''

A [[Minecraft:Bedrock Realms API/Responses#Realm object|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 <code>VISITOR</code>, <code>MEMBER</code>, and <code>OPERATOR</code>.

==== 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 ===

{{Update|section=1}}

Restores a saved backup to the Realm.

The backup ID is URL-encoded. The <code>clientSupportsRetries</code> query parameter is sent without a value.

==== Responses ====

'''Success response'''

The response can contain <code>true</code>. 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 <code>1</code>, <code>2</code>, and <code>3</code>. Selecting a slot is distinct from uploading or replacing its world.

==== Responses ====

'''200 OK'''

Response body:

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

=== PUT /worlds/{id}/open ===

Opens the Realm to players allowed to join.

==== Responses ====

'''200 OK'''

Plain text: <code>true</code>.

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

'''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: <code>true</code>.

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

'''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:

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

=== 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 ===

{{Update|section=1}}

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 [[Minecraft:Realms Hub|Realm Stories]] and related activity. The <code>/api/v1.0/</code> routes below use <code>https://bedrock.frontend.realms.minecraft-services.net</code> and return JSON. The settings endpoint uses the host specified in its description.

{{WIP|section=1}}

== Errors ==

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

{{Navbox Bedrock Edition}}

[[Category:Bedrock Edition]]

Minecraft:Bedrock Realms API - Revision history

SyncBot: Sync: new page from Minecraft