curl --request PATCH \
--url https://api.simpl.gg/v1/lobbies/{lobby_id}/players/{player_id} \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--header 'x-player-id: <x-player-id>' \
--data '
{
"merge": true,
"state": {
"regions": [
"iad",
"dfw"
],
"mmr": 1500
}
}
'{
"player_id": "player_1",
"is_host": true,
"joined_at": "2026-09-21T14:00:00Z",
"state": {
"mmr": 1500,
"team": "team_1",
"regions": [
"iad",
"dfw"
]
}
}Update a player's state
Updates a player’s free-form state. A player may update their own
state; the host may update any player’s. Matchmaking rules read from this
object: mmr, game_version, and the regions array used by the
region rule all live here.
curl --request PATCH \
--url https://api.simpl.gg/v1/lobbies/{lobby_id}/players/{player_id} \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--header 'x-player-id: <x-player-id>' \
--data '
{
"merge": true,
"state": {
"regions": [
"iad",
"dfw"
],
"mmr": 1500
}
}
'{
"player_id": "player_1",
"is_host": true,
"joined_at": "2026-09-21T14:00:00Z",
"state": {
"mmr": 1500,
"team": "team_1",
"regions": [
"iad",
"dfw"
]
}
}Authorizations
Per-project client key, prefixed ck_live_. Player-facing endpoints
only, and browse never returns private lobbies. Safe to ship in a game
binary: a leak exposes one project's player surface, nothing else.
Headers
Identifies the acting player. Trusted verbatim: Simpl performs no authentication or token verification on this value. Bring your own identity system and pass whatever stable id it produces.
1 - 128"player_1"
Path Parameters
Lobby identifier.
"lobby_456"
Player identifier within the lobby.
"player_1"
Body
Updates a player's free-form state. A player may update their own state; a host may update any player's state in their lobby.
Free-form per-player state. Matchmaking rules read fields from here (for
example mmr, game_version, regions). Set via
PATCH /v1/lobbies/{lobby_id}/players/{player_id}.
{
"mmr": 1500,
"team": "team_1",
"regions": ["iad", "dfw"]
}
true merges the supplied keys into the existing state. false
replaces it wholesale.
Response
The updated player.
"player_1"
"2026-09-21T14:00:00Z"
Free-form per-player state. Matchmaking rules read fields from here (for
example mmr, game_version, regions). Set via
PATCH /v1/lobbies/{lobby_id}/players/{player_id}.
{
"mmr": 1500,
"team": "team_1",
"regions": ["iad", "dfw"]
}