Skip to main content
POST
/
game
/
matches
/
{matchId}
/
forfeit
curl -X POST https://teambattles.gg/api/v1/game/matches/match_abc/forfeit \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2a91-unique-per-forfeit" \
  -d '{"forfeitingTeamId":"team_abc","reason":"No-show"}'

{
  "success": true,
  "matchId": "<string>",
  "forfeitedByTeamId": "<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

forfeitingTeamId must be a participant of the match. The forfeit is valid only while the match is ACCEPTED, READY, or IN_PROGRESS; otherwise it returns 409 error_match_not_in_valid_state. The other participating team is recorded as the winner. An unknown match returns 404 error_match_not_found.

​
Idempotency

Supply an optional Idempotency-Key request header to make retries safe: an identical key + body replays the original response, while the same key with a different body returns 409 error_idempotency_key_conflict. The idempotency identity is scoped per match, so reusing the same key on a different match forfeits that match normally.

​
What’s Returned

Returns { "success": true, matchId, forfeitedByTeamId, timestamp }.

​
Request Body

FieldTypeRequiredDescription
forfeitingTeamIdstringYesID of the participating team that forfeits.
reasonstringNoOptional human-readable forfeit reason, recorded on the match.
curl -X POST https://teambattles.gg/api/v1/game/matches/match_abc/forfeit \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2a91-unique-per-forfeit" \
  -d '{"forfeitingTeamId":"team_abc","reason":"No-show"}'

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 forfeiting a match on behalf of one participating team.

​
forfeitingTeamId
string
required

ID of the team that forfeits. Must be a participant of the match.

​
reason
string

Optional human-readable forfeit reason, recorded on the match.

Response

The match was forfeited successfully.

Result of a successful match forfeit.

​
success
boolean
required
​
matchId
string
required

ID of the forfeited match.

​
forfeitedByTeamId
string
required

ID of the team that forfeited.

​
timestamp
string
required

Server response time (ISO 8601).