Skip to main content
PATCH
/
game
/
matches
/
{matchId}
/
status
curl -X PATCH https://teambattles.gg/api/v1/game/matches/match_abc/status \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"IN_PROGRESS"}'

{
  "success": true,
  "matchId": "<string>",
  "previousStatus": "<string>",
  "newStatus": "<string>",
  "timestamp": "<string>"
}

​
Permission Required

This endpoint requires the game.lifecycle permission with read-write access. Your API key must be a game-developer key bound to a game. The binding asserts the match belongs to your bound game before the handler runs: a key bound to a different game, or a non-developer key, receives a 403 error_game_scope_mismatch.

​
Access / Membership Rules

Only these transitions are accepted: READY -> IN_PROGRESS, IN_PROGRESS -> CANCELLED, and ACCEPTED -> CANCELLED. Any other target (or a COMPLETED target) returns 409 error_match_not_in_valid_state. Matches do not complete here - they complete automatically once enough map scores are confirmed, so submit scores via the scores endpoints instead. Use the dedicated forfeit endpoint for forfeits. An unknown match returns 404 error_match_not_found.

​
What’s Returned

Returns { "success": true, matchId, previousStatus, newStatus, timestamp }.

​
Request Body

FieldTypeRequiredDescription
statusstringYesTarget status. Must be a valid transition target: IN_PROGRESS or CANCELLED.
curl -X PATCH https://teambattles.gg/api/v1/game/matches/match_abc/status \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"IN_PROGRESS"}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Path Parameters

​
matchId
string
required

Match ID.

Body

application/json

Request body for updating a match's lifecycle status.

​
status
string
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.

Result of a successful match status transition.

​
success
boolean
required
​
matchId
string
required

ID of the updated match.

​
previousStatus
string
required

Match status before the transition.

​
newStatus
string
required

Match status after the transition.

​
timestamp
string
required

Server response time (ISO 8601).