Skip to main content
POST
/
game
/
matches
/
{matchId}
/
scores
/
{mapIndex}
curl -X POST https://teambattles.gg/api/v1/game/matches/match_abc/scores/0 \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mapId":"de_dust2","creatorTeamScore":13,"opponentTeamScore":7}'

{
  "success": true,
  "mapIndex": 0,
  "scoreStatus": "<string>"
}

​
Permission Required

This endpoint requires the game.scores permission with write access. (game.scores is a write-level permission - its levels are none or write, not read-write.) 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

The {mapIndex} path segment is the zero-based map index within the series. Game-developer scores are auto-confirmed on submission. creatorTeamScore and opponentTeamScore must be non-negative integers in range 0-1000. An unknown match returns 404 error_match_not_found.

​
What’s Returned

Returns { "success": true, mapIndex, scoreStatus }, where scoreStatus is always CONFIRMED on success.

​
Request Body

FieldTypeRequiredDescription
mapIdstringYesIdentifier of the map that was played.
creatorTeamScorenumberYesCreator team score (integer, 0-1000).
opponentTeamScorenumberYesOpponent (accepted) team score (integer, 0-1000).
screenshotUrlsarrayNoOptional public https screenshot URLs.
screenshotStorageIdsarrayNoOptional storage IDs from POST /uploads/image-url (preferred).
playerStatsobjectNoOptional per-player stats keyed by user ID.
curl -X POST https://teambattles.gg/api/v1/game/matches/match_abc/scores/0 \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mapId":"de_dust2","creatorTeamScore":13,"opponentTeamScore":7}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Path Parameters

​
matchId
string
required

Match ID.

​
mapIndex
string
required

Zero-based index of the map within the series.

Body

application/json

Request body for submitting a single map's score (mapIndex comes from the path).

​
mapId
string
required

Identifier of the map that was played.

​
creatorTeamScore
integer
required

Score for the creator team (integer, 0-1000).

Required range: 0 <= x <= 1000
​
opponentTeamScore
integer
required

Score for the opponent (accepted) team (integer, 0-1000).

Required range: 0 <= x <= 1000
​
screenshotUrls
string[]

Optional external screenshot URLs supporting the reported score. Each must be a public https URL. Prefer screenshotStorageIds (validated blobs) where possible.

​
screenshotStorageIds
string[]

Optional storage IDs for screenshots uploaded via POST /uploads/image-url. Preferred over screenshotUrls: each is validated (size, content-type, ownership) and resolved to a URL server-side.

​
playerStats
object

Optional per-player stats keyed by user ID.

Response

The map score was submitted and confirmed.

Result of submitting a single map score.

​
success
boolean
required
​
mapIndex
integer
required

Index of the map that was scored.

Required range: -9007199254740991 <= x <= 9007199254740991
​
scoreStatus
string
required

Confirmation state, always "CONFIRMED" on success.