v20

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-011984401.2 MB
Game: Matches

Update a match's lifecycle status

Transitions a match between lifecycle states (validated against allowed transitions). Requires the game.lifecycle:read-write permission. Supports an optional Idempotency-Key request header that deduplicates concurrent duplicate submissions: while one request is in flight, a second request with the same key and body resolves to the same outcome, and the same key with a different body returns 409 error_idempotency_key_conflict. The idempotency identity is scoped per match and per target status. Note that this endpoint validates the live match state first, so a sequential retry sent after the transition has already succeeded returns the normal transition error (error_match_not_in_valid_state) - the live state no longer permits the transition - rather than a replayed success.

patch/game/matches/{matchId}/status

Path parameters

matchIdstring required

Match ID.

Match ID.

Request body

statusstring required

Target status. Allowed transitions: READY -> IN_PROGRESS, IN_PROGRESS -> COMPLETED|CANCELLED, ACCEPTED -> CANCELLED. COMPLETED is not accepted directly (matches complete automatically once scores are confirmed).

Response

The match status was transitioned successfully.

successtrue required
matchIdstring required

ID of the updated match.

previousStatusstring required

Match status before the transition.

newStatusstring required

Match status after the transition.

timestampstring required

Server response time (ISO 8601).