Minecraft:Mojang API - Revision history

SyncBot: Sync: updated from Minecraft

2026-06-01T11:11:15Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:11, 1 June 2026
Line 1,597:		Line 1,597:
	[[Minecraft:lzh:魔贊卯口]]		[[Minecraft:lzh:魔贊卯口]]
	[[Minecraft:zh:Mojang API]]		[[Minecraft:zh:Mojang API]]
	~~[[Minecraft:ko:Mojang API]]~~

SyncBot: Sync: updated from Minecraft

2026-05-31T11:11:45Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:11, 31 May 2026
Line 1,597:		Line 1,597:
	[[Minecraft:lzh:魔贊卯口]]		[[Minecraft:lzh:魔贊卯口]]
	[[Minecraft:zh:Mojang API]]		[[Minecraft:zh:Mojang API]]
			[[Minecraft:ko:Mojang API]]

SyncBot: Sync: updated from Minecraft

2026-05-27T11:12:35Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:12, 27 May 2026
Line 1,021:		Line 1,021:

	== Peer-to-peer multiplayer networking ==		== Peer-to-peer multiplayer networking ==
			{{outdated\|section=y\|edition=java\|never=y\|This feature was present only in development versions and the related API endpoints are no longer available.}}

	Peer-to-peer (P2P) multiplayer networking was introduced in [[Minecraft:Java Edition 26.2 Snapshot 7\|Minecraft Java Edition 26.2 ~~Snapshot 7~~]]. It allows a host's singleplayer world to be joinable by friends over Peer-to-Peer [https://wikipedia.org/wiki/WebRTC WebRTC] data channels. A Mojang-hosted ''signaling service'' handles the handshake, gameplay traffic flows peer-to-peer (using [[Minecraft:w:Interactive_Connectivity_Establishment\|ICE]]). The protocol described below is unstable and likely to change.		Peer-to-peer (P2P) multiplayer networking was introduced in [[Minecraft:Java Edition 26.2 Snapshot 7]] and removed in [[Minecraft:Java Edition 26.2 Pre-Release 1]]. It allows a host's singleplayer world to be joinable by friends over Peer-to-Peer [https://wikipedia.org/wiki/WebRTC WebRTC] data channels. A Mojang-hosted ''signaling service'' handles the handshake, gameplay traffic flows peer-to-peer (using [[Minecraft:w:Interactive_Connectivity_Establishment\|ICE]]). The protocol described below is unstable and likely to change.

	General Properties:		General Properties:

SyncBot: Sync: updated from Minecraft

2026-05-25T11:12:54Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:12, 25 May 2026
Line 1,231:		Line 1,231:
	\|S→C request		\|S→C request
	\|<code>Signaling_ReceiveMessage_v1_0</code>		\|<code>Signaling_ReceiveMessage_v1_0</code>
	\|<code>{ From, Message, Id }</code>		\|<code>[{ From, Message, Id }]</code>
	\|<code>{}</code> (ACK only if <code>id</code> is present)		\|<code>{}</code> (ACK only if <code>id</code> is present)
	\|}		\|}

SyncBot: Sync: updated from Minecraft

2026-05-24T11:12:32Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:12, 24 May 2026
Line 1,226:		Line 1,226:
	\|C→S request		\|C→S request
	\|<code>Signaling_SendClientMessage_v1_0</code>		\|<code>Signaling_SendClientMessage_v1_0</code>
	\|<code>~~[null~~, ~~"<toPmid>"~~, ~~"<innerJsonString>"]~~</code>		\|<code>{ messageId, toPlayerId, message }</code>
	\|<code>null</code> / <code>{}</code> (client ignores on success)		\|<code>null</code> / <code>{}</code> (client ignores on success)
	\|-		\|-
	\|S→C request		\|S→C request
	\|<code>Signaling_ReceiveMessage_v1_0</code>		\|<code>Signaling_ReceiveMessage_v1_0</code>
	\|<code>[{ From, Message, Id~~? }]</code> or <code>{ …~~ }</code>		\|<code>{ From, Message, Id }</code>
	\|<code>{}</code> (ACK only if <code>id</code> is present)		\|<code>{}</code> (ACK only if <code>id</code> is present)
	\|}		\|}

	The third parameter of <code>Signaling_SendClientMessage_v1_0</code> is a '''stringified JSON''' value, not a nested JSON object. The signaling service treats it opaquely and forwards it verbatim as the <code>Message</code> field of <code>Signaling_ReceiveMessage_v1_0</code> on the recipient's side.		The third parameter (<code>message</code>) of <code>Signaling_SendClientMessage_v1_0</code> is a '''stringified JSON''' value, not a nested JSON object. The signaling service treats it opaquely and forwards it verbatim as the <code>Message</code> field of <code>Signaling_ReceiveMessage_v1_0</code> on the recipient's side.

	==== Server-side errors ====		==== Server-side errors ====
Line 1,433:		Line 1,433:
	"id": 2,		"id": 2,
	"method": "Signaling_SendClientMessage_v1_0",		"method": "Signaling_SendClientMessage_v1_0",
	"params": [		"params": {
	null,		"messageId": "5c2a87a0-2bd1-4b9f-9c50-1c2d5b4f8a91", // could be UUID with dashes or null, if it's null, signaling server server will generate a random UUID as messageId
	"069a79f4-44e9-4726-a5be-fca90e38aaf5",		"toPlayerId": "069a79f4-44e9-4726-a5be-fca90e38aaf5", // PMID of recipient
	"{\"type\":\"JOIN_REQUEST\",\"sessionId\":\"6b8b4567-327d-4ee8-90c2-0d8c1f9f1d9e\"}"		"message": "{\"type\":\"JOIN_REQUEST\",\"sessionId\":\"6b8b4567-327d-4ee8-90c2-0d8c1f9f1d9e\"}" // message to send
	]		}
	}		}
	</syntaxhighlight>		</syntaxhighlight>
Line 1,455:		Line 1,455:
	"method": "Signaling_ReceiveMessage_v1_0",		"method": "Signaling_ReceiveMessage_v1_0",
	"params": {		"params": {
	"From": "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6",		"From": "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6", // PMID of sender
	"Message": "{\"type\":\"~~OFFER~~\",\"sessionId\":\"6b8b4567-327d-4ee8-90c2-0d8c1f9f1d9e~~\",\"sdp\":\"v=0\\r\\no=- ...~~\"}",		"Message": "{\"type\":\"JOIN_REQUEST\",\"sessionId\":\"6b8b4567-327d-4ee8-90c2-0d8c1f9f1d9e\"}", // message received
	"Id": "5c2a87a0-2bd1-4b9f-9c50-1c2d5b4f8a91"		"Id": "5c2a87a0-2bd1-4b9f-9c50-1c2d5b4f8a91" // messageId
	}		}
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	* <code>From</code>: PMID of the sending peer, as a UUID string with dashes.
	* <code>Message</code>: stringified JSON envelope as described above.
	* <code>Id</code>: optional server-side delivery id; opaque to the client.

	If the request carries a numeric <code>id</code>, the client must immediately replies with <code>{"jsonrpc":"2.0","id":<id>,"result":{}}</code> as an ACK, otherwise the signaling service will not deliver later <code>Signaling_ReceiveMessage_v1_0</code> requests on the same WebSocket connection.		If the request carries a numeric <code>id</code>, the client must immediately replies with <code>{"jsonrpc":"2.0","id":<id>,"result":{}}</code> as an ACK, otherwise the signaling service will not deliver later <code>Signaling_ReceiveMessage_v1_0</code> requests on the same WebSocket connection.

SyncBot: Sync: updated from Minecraft

2026-05-23T11:13:20Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:13, 23 May 2026
Line 806:		Line 806:
	* {{Nbt\|compound\|Root tag}}		* {{Nbt\|compound\|Root tag}}
	** {{Nbt\|string\|name}}: Profile name of the player to add or remove. Optional.		** {{Nbt\|string\|name}}: Profile name of the player to add or remove. Optional.
	** {{Nbt\|string\|profileId}}: UUID of the player to add or remove, Optional.		** {{Nbt\|string\|profileId}}: UUID of the player to add or remove. Could be UUID with or without dashes Optional.
	** {{Nbt\|string\|updateType}}: Action to perform. Values: <code>ADD</code> for sending or accepting friend requests, <code>REMOVE</code> for removing friends or denying friend requests.		** {{Nbt\|string\|updateType}}: Action to perform. Values: <code>ADD</code> for sending or accepting friend requests, <code>REMOVE</code> for removing friends or denying friend requests.
	</div>		</div>
Line 888:		Line 888:
	*** {{Nbt\|string\|value}}: Currently the game client always sends <code>null</code>. See below.		*** {{Nbt\|string\|value}}: Currently the game client always sends <code>null</code>. See below.
	*** {{Nbt\|list\|invites}}: List of invited players. Optional.		*** {{Nbt\|list\|invites}}: List of invited players. Optional.
	**** {{Nbt\|string}}: UUID of a invited player. ~~Must~~ be UUID with dashes.		**** {{Nbt\|string}}: UUID of a invited player. Could be UUID with or without dashes.
	</div>		</div>

Line 1,454:		Line 1,454:
	"id": 17,		"id": 17,
	"method": "Signaling_ReceiveMessage_v1_0",		"method": "Signaling_ReceiveMessage_v1_0",
	"params": [{		"params": {
	"From": "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6",		"From": "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6",
	"Message": "{\"type\":\"OFFER\",\"sessionId\":\"6b8b4567-327d-4ee8-90c2-0d8c1f9f1d9e\",\"sdp\":\"v=0\\r\\no=- ...\"}",		"Message": "{\"type\":\"OFFER\",\"sessionId\":\"6b8b4567-327d-4ee8-90c2-0d8c1f9f1d9e\",\"sdp\":\"v=0\\r\\no=- ...\"}",
	"Id": "5c2a87a0-2bd1-4b9f-9c50-1c2d5b4f8a91"		"Id": "5c2a87a0-2bd1-4b9f-9c50-1c2d5b4f8a91"
	}]		}
	}		}
	</syntaxhighlight>		</syntaxhighlight>

SyncBot: Sync: updated from Minecraft

2026-05-21T11:16:06Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:16, 21 May 2026
Line 102:		Line 102:
	These endpoints do not need an access token, and some endpoints can query registered account that do not own the game.		These endpoints do not need an access token, and some endpoints can query registered account that do not own the game.

	=== Query player's ~~username~~ ===		=== Query player's UUID ===

	; Input		; Input
Line 135:		Line 135:
	* HTTP 404 is returned if no player with such name exists.		* HTTP 404 is returned if no player with such name exists.

	=== Query player's ~~UUID~~ ===		=== Query player's username ===

	; Input		; Input
Line 144:		Line 144:

	; Response		; Response
	The same as [[#Query player's ~~username~~]].		The same as [[#Query player's UUID]].

	=== Query player UUIDs in batch ===		=== Query player UUIDs in batch ===
Line 1,003:		Line 1,003:
	"value": "87c83220-965c-4d65-867f-8718f5ba04a6",		"value": "87c83220-965c-4d65-867f-8718f5ba04a6",
	"invited": true		"invited": true
	}		},
	"lastUpdated": "2026-05-15T19:26:12Z"		"lastUpdated": "2026-05-15T19:26:12Z"
	},		},
Line 1,013:		Line 1,013:
	"value": "f289feed-30ab-4039-bef8-5752ea9d2c1c",		"value": "f289feed-30ab-4039-bef8-5752ea9d2c1c",
	"invited": false		"invited": false
	}		},
	"lastUpdated": "2026-05-15T19:26:32Z"		"lastUpdated": "2026-05-15T19:26:32Z"
	}		}
Line 1,034:		Line 1,034:
	The signaling service routes messages by the '''PMID'''. A friend's PMID is obtained from the <code>pmid</code> field of their entry in their [[#Presence\|presence]] response.		The signaling service routes messages by the '''PMID'''. A friend's PMID is obtained from the <code>pmid</code> field of their entry in their [[#Presence\|presence]] response.

	When a peer-to-peer connection completes, the host resolves the guest's profile UUID locally from the PMID via its presence cache and '''pins it to the connection'''. The standard <code>ServerboundHelloPacket</code> profile UUID sent from the guest is ignored; the server obtains the guest's profile UUID via the normal login flow, and rejects the connection if the result does not match the UUID from its PMID presence cache. See [[#~~Security model\|Security model~~]] below.		When a peer-to-peer connection completes, the host resolves the guest's profile UUID locally from the PMID via its presence cache and '''pins it to the connection'''. The standard <code>ServerboundHelloPacket</code> profile UUID sent from the guest is ignored; the server obtains the guest's profile UUID via the normal login flow, and rejects the connection if the result does not match the UUID from its PMID presence cache. See [[#Full Connection sequence]] below.

	Authentication uses the same Mojang access token as the rest of the Mojang API, but is sent in the <code>x-mojangauth</code> HTTP header rather than as a <code>Bearer</code> token.		Authentication uses the same Mojang access token as the rest of the Mojang API, but is sent in the <code>x-mojangauth</code> HTTP header rather than as a <code>Bearer</code> token.
Line 1,089:		Line 1,089:
	The response may contains a <code>Session-Id</code> header matches the one you send in the request as-is, or will also omit it if you omitted it in the request.		The response may contains a <code>Session-Id</code> header matches the one you send in the request as-is, or will also omit it if you omitted it in the request.

	<code>result.signalingUri</code> may vary by where you send the request~~. The server seems always return a signaling server nearest to you~~. It doesn't matter if you and your friends connect to different signaling servers, although P2P multiplayer session invites and join requests are transferred on the signaling server, players connect to differnet signaling servers could still receive invites or join requests.		<code>result.signalingUri</code> may vary by multiple reasons, such as data encoded in access token or where you send the request. It doesn't matter if you and your friends connect to different signaling servers, although P2P multiplayer session invites and join requests are transferred on the signaling server, players connect to differnet signaling servers could still receive invites or join requests.

	For reference, <code>result.signalingUri</code> currently follows the format <code>wss://signal-{location}.franchise.minecraft-services.net</code>, where <code>{location}</code> corresponds to one of the following Microsoft Azure region identifiers:		For reference, <code>result.signalingUri</code> currently follows the format <code>wss://signal-{location}.franchise.minecraft-services.net</code>, where <code>{location}</code> corresponds to one of the following Microsoft Azure region identifiers:

SyncBot: Sync: updated from Minecraft

2026-05-20T11:15:41Z

Sync: updated from Minecraft

Show changes

SyncBot: Sync: updated from Minecraft

2026-05-19T11:15:28Z

Sync: updated from Minecraft

Show changes

SyncBot: Sync: updated from Minecraft

2026-05-18T11:15:50Z

Sync: updated from Minecraft

← Older revision		Revision as of 11:15, 18 May 2026
Line 1,059:		Line 1,059:
	\|<code><nowiki>https://signaling-afd.franchise.minecraft-services.net</nowiki></code>		\|<code><nowiki>https://signaling-afd.franchise.minecraft-services.net</nowiki></code>
	\|}		\|}
			The <code>staging</code> URL does not work and produces an Azure Front Door Service 404 Not found page<ref>https://signaling-afd.stage-6fd5f759.franchise.minecraft-services.net</ref>.

	==== Discover the signaling WebSocket URL ====		==== Discover the signaling WebSocket URL ====
Line 1,066:		Line 1,067:
	<code>/api/v1.0/configuration/java</code>		<code>/api/v1.0/configuration/java</code>

	Headers ~~(required on every signaling HTTP request)~~:		Headers:
	* <code>x-mojangauth</code>: ''Minecraft access token''		* <code>x-mojangauth</code>: ''Minecraft access token''. Required.
	* <code>Session-Id</code>: ~~stable per~~-~~launch UUID~~		* <code>Session-Id</code>: Could be any non-empty value. Optional. See below.
	* <code>Request-Id</code>: ~~fresh~~ per-request UUID		* <code>Request-Id</code>: Fresh per-request UUID with or without dashes, but could be also any non-empty value. Optional. See below.

			Both <code>Session-Id</code> and <code>Request-Id</code> can be any non-empty values or even be omitted. The server may behaves differently but it won't return errors. See below for details.

	; Response		; Response
Line 1,079:		Line 1,082:
	*** {{Nbt\|string\|pingFrequency}}: A time in <code>hh:mm:ss</code> format, which tells the client how long to wait between sending ping messages.		*** {{Nbt\|string\|pingFrequency}}: A time in <code>hh:mm:ss</code> format, which tells the client how long to wait between sending ping messages.
	</div>		</div>

			The response will always contains a <code>Request-Id</code> header, which is a UUID without dashes matches the one you send in the request. However, if you omitted it in the request or filled it with other values cannot be recognized as UUID, it will be a new UUID without dashes generated by the server itself.

			The response may contains a <code>Session-Id</code> header matches the one you send in the request as-is, or will also omit it if you omitted it in the request.

			<code>result.signalingUri</code> may vary by where you send the request. The server seems always return a signaling server nearest to you. It doesn't matter if you and your friends connect to different signaling servers, although P2P multiplayer session invites and join requests are transferred on the signaling server, players connect to differnet signaling servers could still receive invites or join requests.

			For reference, <code>result.signalingUri</code> currently follows the format <code>wss://signal-{location}.franchise.minecraft-services.net</code>, where <code>{location}</code> corresponds to one of the following Microsoft Azure region identifiers:

			* <code>brazilsouth</code>
			* <code>centralindia</code>
			* <code>eastasia</code>
			* <code>eastus2</code>
			* <code>mexicocentral</code>
			* <code>northeurope</code>
			* <code>westeurope</code>
			* <code>westus2</code>

			These '''shouldn't be hardcoded''', as they are subject to change in the future.

	; Example		; Example
Line 1,091:		Line 1,113:
	</syntaxhighlight>		</syntaxhighlight>

	The client caches <code>signalingUri</code> for 5 minutes.		The client caches the <code>signalingUri</code> for 5 minutes.

	==== Open the signaling WebSocket ====		==== Open the signaling WebSocket ====
Line 1,105:		Line 1,127:
	If the WebSocket disconnects, and the client still needs signaling, it schedules a reconnect 1 second later. If the client no longer needs signaling, it stays disconnected.		If the WebSocket disconnects, and the client still needs signaling, it schedules a reconnect 1 second later. If the client no longer needs signaling, it stays disconnected.

	The WebSocket server disconnects the client automatically after 120 seconds of inactivity. This ~~includes~~ all messages and isn't limited to <code>System_Ping_v1_0</code> messages.		The WebSocket server disconnects the client automatically after 120 seconds of inactivity, or after 60 seconds if no data is sent since the connection established. In both cases, the connection is terminated forcefully with close code <code>1006</code> (<code>Abnormal Closure</code>). This is applicable for all messages and isn't limited to <code>System_Ping_v1_0</code> messages.

	=== WebSocket Framing ===		=== WebSocket Framing ===
Line 1,190:		Line 1,212:

	{\| class="wikitable"		{\| class="wikitable"
	!~~{{cd\|data.Code}}~~		!Named Error code
	!~~Mapped client-side behaviour~~		!Numeric Error code
			!Error Message
			!Explenation
	\|-		\|-
	\|<code>MissingOrExpiredIdentity</code>		\|<code>MissingOrExpiredIdentity</code>
	~~\|Generic signaling-rejected exception; the matching outgoing request fails and connection listeners are notified.~~		\|<code>-32000</code>
	\|-		\|Player not registered with the service.
	\|<code>~~UnknownPlayer~~</code>		\|The target PMID is Invalid
	\|~~Same as above.~~
	\|-
	~~\|''(any other Code, or if message body contains the substring'' <code>~~not registered~~</code>'')''~~
	~~\|Unknown-player exception; same downstream effects~~.
	\|-
	~~\|''(missing or unrecognised)''~~
	~~\|Generic signaling-rejected exception.~~
	\|}		\|}

Line 1,231:		Line 1,248:
	**** {{Nbt\|string\|Password}}: TURN password (long-term credential).		**** {{Nbt\|string\|Password}}: TURN password (long-term credential).
	**** {{Nbt\|list\|Urls}}: List of STUN/TURN URLs.		**** {{Nbt\|list\|Urls}}: List of STUN/TURN URLs.
	***** {{Nbt\|string}}: e.g. <code>stun:...</code>, <code>turn:...</code>		***** {{Nbt\|string}}: TURN/STUN URL (e.g. <code>stun:...</code>, <code>turn:...</code>)
	</div>		</div>

Line 1,398:		Line 1,415:
	==== Service envelope (delivery failure) ====		==== Service envelope (delivery failure) ====

	The inner <code>Message</code> may also be a '''service envelope''' indicating a delivery failure rather than a peer message. A service envelope is a JSON object with a top-level numeric <code>Code</code> and a <code>Message</code> field:		The inner <code>Message</code> may also be a '''service envelope''' indicating a delivery failure rather than a peer message. A service envelope is a JSON object with a top-level numeric <code>Code</code> and a <code>Message</code> field. It does not include a <code>type</code> field:

	<syntaxhighlight lang="json">		<syntaxhighlight lang="json">
Line 1,427:		Line 1,444:

	# A sends <code>Signaling_TurnAuth_v1_0</code> to obtain TURN credentials and constructs an <code>RTCIceServer</code>.		# A sends <code>Signaling_TurnAuth_v1_0</code> to obtain TURN credentials and constructs an <code>RTCIceServer</code>.
	# A generates a fresh <code>sessionId</code> and sends <code>JOIN_REQUEST</code> targeted at B's PMID, wrapped in <code>Signaling_SendClientMessage_v1_0</code>. The join request expires in one minute on As side.		# A generates a fresh <code>sessionId</code> and sends <code>JOIN_REQUEST</code> targeted at B's PMID, wrapped in <code>Signaling_SendClientMessage_v1_0</code>. The join request expires after one minute on As side.
	# B's client receives <code>JOIN_REQUEST</code> via <code>Signaling_ReceiveMessage_v1_0</code>. After friend and hosting checks, it either:		# B's client receives <code>JOIN_REQUEST</code> via <code>Signaling_ReceiveMessage_v1_0</code>. After friend and hosting checks, it either:
	#* Auto-accepts (if A is in B's outstanding presence <code>invites</code>); or		#* Auto-accepts (if A is in B's outstanding presence <code>invites</code>); or
Line 1,480:		Line 1,497:
	* When the WebRTC <code>bufferedAmount</code> on the data channel exceeds 1 MiB, the Netty channel is marked '''non-writable''' and the application is expected to back off.		* When the WebRTC <code>bufferedAmount</code> on the data channel exceeds 1 MiB, the Netty channel is marked '''non-writable''' and the application is expected to back off.
	* When <code>bufferedAmount</code> falls back below 256 KiB, the Netty channel is marked '''writable''' again and writes resume.		* When <code>bufferedAmount</code> falls back below 256 KiB, the Netty channel is marked '''writable''' again and writes resume.


	== History ==		== History ==