Skip to main content
POST
/
leagues
/
{identifier}
/
penalties
/
create
curl -X POST https://teambattles.gg/api/v1/leagues/my-league/penalties/create \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "jh7team123",
    "gameId": "jh7game123",
    "type": "POINT_DEDUCTION",
    "value": 10,
    "reason": "Roster violation"
  }'

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

​
Permission Required

This endpoint requires a league-operator API key bound to this league with the penalties league capability, plus the leagueOperatorApi plan feature (api_pro or higher). A free key receives 403 error_api_feature_required.

​
Access / Membership Rules

You must have a MANAGER or higher role in the league (or be a TeamBattles staff member) to issue a penalty. If you lack the required access, you’ll receive a 403 error. The {identifier} path parameter is the league slug - the URL-friendly league name (e.g., my-league).

​
What’s Returned

Issues a warning, match-forfeit penalty, or point deduction to a league team. On success the response is { "success": true, "penaltyId": "<id>", "timestamp": "<ISO 8601>" }.

​
Request Body

ParameterTypeRequiredDescription
teamIdstringYesTeam ID receiving the penalty.
gameIdstringYesGame ID for the league penalty.
typestringYesPenalty type: POINT_DEDUCTION, MATCH_FORFEIT, or WARNING.
reasonstringYesReason for the penalty (1-500 characters).
seasonIdstringNoLeague season ID the penalty applies to.
valuenumberNoPoint value for POINT_DEDUCTION (integer, 1-1000).
curl -X POST https://teambattles.gg/api/v1/leagues/my-league/penalties/create \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "jh7team123",
    "gameId": "jh7game123",
    "type": "POINT_DEDUCTION",
    "value": 10,
    "reason": "Roster violation"
  }'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Path Parameters

​
identifier
string
required

League slug or Convex league ID.

Body

application/json

Creates a league team penalty.

​
teamId
string
required

Team ID receiving the penalty.

Minimum string length: 1
​
gameId
string
required

Game ID for the league penalty.

Minimum string length: 1
​
type
enum<string>
required

Penalty type.

Available options:
POINT_DEDUCTION,
MATCH_FORFEIT,
WARNING
​
reason
string
required

Reason for the penalty.

Required string length: 1 - 500
​
seasonId
string

Optional league season ID for the penalty.

Minimum string length: 1
​
value
integer

Point value for POINT_DEDUCTION (integer, 1-1000).

Required range: x <= 1000

Response

The league penalty was created.

​
success
boolean
required
​
penaltyId
string
required

Created league penalty ID.

​
timestamp
string
required

Response generation time (ISO 8601).