Skip to main content
POST
/
matches
/
{matchId}
/
forfeit
curl -X POST https://teambattles.gg/api/v1/matches/jm7match123/forfeit \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Cannot field a full roster"}'

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

​
Permission Required

This endpoint requires matches.user_matches:read-write on your API key. A free (api_free) key receives 403 error_api_feature_required; this requires an api_pro+ plan.

​
Access / Membership Rules

The forfeit is recorded as the API key owner, derived from the key itself - it is never accepted as a body field. The owner must captain one participating team. A personal key can only forfeit matches for teams its owner actually captains - the route binding is a no-op and this authorization is enforced inside Convex. A non-personal key receives 403 API_KEY_PERMISSION_DENIED. This route accepts an optional Idempotency-Key header so retries are safe.

​
Request Body

FieldTypeRequiredDescription
reasonstringNoOptional forfeit reason.

​
What’s Returned

Returns success: true, the matchId, and a timestamp. Mintlify renders the full schema from the spec below. 
curl -X POST https://teambattles.gg/api/v1/matches/jm7match123/forfeit \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Cannot field a full roster"}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Path Parameters

​
matchId
string
required

Match ID.

Body

application/json

Forfeits the match as the API key owner.

​
reason
string

Optional forfeit reason.

Response

The match was forfeited successfully.

​
success
boolean
required
​
matchId
string
required
​
timestamp
string
required