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

{
  "success": true,
  "submitted": [
    {
      "matchId": "<string>",
      "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. There is no per-match route binding here (one call spans many matches with possibly different matchIds), so each item is independently scope-checked in the handler against your bound game. A non-developer key, or a key with no bound game, receives a 403 error_game_scope_mismatch.

​
Access / Membership Rules

A batch may contain 1-50 items (each carries its own matchId); over the cap returns 400 error_invalid_num_items. Each item is checked independently: an item whose match does not belong to your bound game (or otherwise fails) is rejected in its own per-item envelope (status: "failed", error = bare error_* code) without failing the whole request - the top-level response is always HTTP 200, so inspect each item’s status. Score submission is naturally idempotent (an unconfirmed map is overwritten on re-submit; an already-confirmed map returns a per-item error_score_already_submitted_by_game), so a retried batch is safe and this endpoint does not use an Idempotency-Key.

​
Rate Limiting

Batch items are metered per item against a dedicated per-key bucket (capacity 200, refilling 2/sec), separate from the standard per-request limiter. A 50-item batch charges 50 tokens; exceeding the bucket returns 429 error_api_rate_limited with rate-limit headers.

​
What’s Returned

Returns { success, submitted, count }. submitted[] is the per-item result array in submission order (each { matchId, mapIndex, status, error? }), count is the number confirmed, and success is true only when every item was confirmed.

​
Request Body

FieldTypeRequiredDescription
itemsarrayYesMap-score items across one or more matches (1-50 entries).
Each items[] entry:
FieldTypeRequiredDescription
matchIdstringYesID of the match this map score belongs to.
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/batch-scores \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"matchId":"match_abc","mapIndex":0,"mapId":"de_dust2","creatorTeamScore":13,"opponentTeamScore":7},{"matchId":"match_xyz","mapIndex":0,"mapId":"de_mirage","creatorTeamScore":10,"opponentTeamScore":13}]}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Body

application/json

Request body for submitting map scores across multiple matches in a single call (capped at 50 items).

​
items
object[]
required

Map scores to submit across one or more matches. 1-50 entries.

Required array length: 1 - 50 elements

Response

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

Result of a multi-match batch map-score submission. Always returned with HTTP 200; inspect per-item status.

​
success
boolean
required

True only when every submitted item was confirmed.

​
submitted
object[]
required

Per-item results, in submission order.

​
count
integer
required

Number of items that were confirmed.

Required range: -9007199254740991 <= x <= 9007199254740991