Skip to main content
POST
/
matches
/
{matchId}
/
lobby-code
curl -X POST https://teambattles.gg/api/v1/matches/jm7match123/lobby-code \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lobbyCode": "TB-1234"}'

{
  "success": true,
  "lobbyCode": "<string>",
  "statusChanged": true,
  "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 lobby code is set 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. Setting the code may advance the match status (reflected in statusChanged). A personal key can only set the lobby code for matches whose teams its owner 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
lobbyCodestringYesLobby code to set for the match (1-50 characters).

​
What’s Returned

Returns success: true, the lobbyCode that was stored, a statusChanged boolean indicating whether the match status advanced, and a timestamp. Mintlify renders the full schema from the spec below. 
curl -X POST https://teambattles.gg/api/v1/matches/jm7match123/lobby-code \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lobbyCode": "TB-1234"}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Path Parameters

​
matchId
string
required

Match ID.

Body

application/json

Sets or updates the match lobby code as the API key owner.

​
lobbyCode
string
required

Lobby code to set for the match.

Required string length: 1 - 50

Response

The match lobby code was updated.

​
success
boolean
required
​
lobbyCode
string
required
​
statusChanged
boolean
required
​
timestamp
string
required