Skip to main content
POST
/
matches
/
{matchId}
/
cancel
curl -X POST https://teambattles.gg/api/v1/matches/jm7match123/cancel \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Opponent no-showed"}'

{
  "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 cancellation is performed as the API key owner, derived from the key itself - it is never accepted as a body field. The owner must be able to manage the match: captain a participating team or be an admin. Past the league grace period, an accepted league match is treated as a forfeit rather than a plain cancellation. A personal key can only cancel matches its owner can manage - 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 cancellation 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/cancel \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Opponent no-showed"}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Path Parameters

​
matchId
string
required

Match ID.

Body

application/json

Cancels the match as the API key owner.

​
reason
string

Optional cancellation reason.

Response

The match was cancelled successfully.

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