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

{
  "success": true,
  "submitted": [
    {
      "mapIndex": 0,
      "status": "<string>",
      "error": "<string>"
    }
  ],
  "count": 0
}

​
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

This is batch-by-design: the body carries a maps[] array (at least one entry). Game-developer scores are auto-confirmed on submission. Each map’s creatorTeamScore and opponentTeamScore must be non-negative integers in range 0-1000. A single map can fail (e.g. already confirmed) without aborting the others - its outcome is reported in its per-map result. An unknown match returns 404 error_match_not_found.

​
What’s Returned

Returns { success, submitted, count }. submitted[] is the per-map result array (each { mapIndex, status, error? }, status being confirmed or failed), count is the number confirmed, and success is true only when every map was confirmed.

​
Request Body

FieldTypeRequiredDescription
mapsarrayYesOne or more map scores to submit (at least one entry).
Each maps[] entry:
FieldTypeRequiredDescription
mapIndexnumberYesZero-based index of the map within the series.
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 \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"maps":[{"mapIndex":0,"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.

Body

application/json

Request body for submitting one or more map scores in a single call.

​
maps
object[]
required

Map scores to submit. Must contain at least one entry.

Minimum array length: 1

Response

Per-map submission results. success is true only when every map was confirmed.

Result of a batch map-score submission.

​
success
boolean
required

True only when every submitted map score was confirmed.

​
submitted
object[]
required

Per-map results, in submission order.

​
count
integer
required

Number of map scores that were confirmed.

Required range: -9007199254740991 <= x <= 9007199254740991