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

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

​
Permission Required

This endpoint requires matches.team_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 submission is recorded as the API key owner, derived from the key itself - it is never accepted as a body field. Only a team captain can submit (or overwrite) a map score. The submitted score starts as PENDING and must be confirmed by the opposing team’s captain before it counts (see Confirm A Map Score). A personal key can only submit scores 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.

​
Request Body

FieldTypeRequiredDescription
mapIndexnumberYesZero-based map index (non-negative integer).
mapIdstringYesMap identifier string (e.g. dust2).
creatorTeamScorenumberYesCreator team score (integer, 0 to the per-game maximum).
opponentTeamScorenumberYesAccepted/opponent team score (integer, 0 to the per-game maximum).
screenshotUrlsarrayNoExternal screenshot URLs (validated as public https server-side, max 10).
screenshotStorageIdsarrayNoConvex storage IDs from POST /uploads/image-url (validated, max 10; preferred over URLs).

​
What’s Returned

Returns success: true, action: "submitted", the mapIndex, and scoreStatus: "PENDING". Mintlify renders the full schema from the spec below. 
curl -X POST https://teambattles.gg/api/v1/matches/jm7match123/scores \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mapIndex": 0, "mapId": "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

Map score submission payload for a single map.

​
mapIndex
integer
required

Zero-based map index. Must be a non-negative integer.

Required range: 0 <= x <= 9007199254740991
​
mapId
string
required

Map identifier string (e.g. dust2).

​
creatorTeamScore
integer
required

Creator team score (integer, 0-1000).

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

Accepted/opponent team score (integer, 0-1000).

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

Optional external screenshot URLs (validated as public https server-side, max 10). Prefer screenshotStorageIds for validated blobs.

Maximum array length: 10
​
screenshotStorageIds
string[]

Optional Convex storage ids from POST /api/v1/uploads/image-url (validated for size + content-type, max 10; preferred over screenshotUrls).

Maximum array length: 10

Response

Map score submitted.

Result of submitting or confirming a map score.

​
success
boolean
required
​
action
string
required

Action performed, e.g. "submitted" or "confirmed".

​
mapIndex
integer
required

Zero-based map index that was affected.

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

Resulting score status, e.g. PENDING or CONFIRMED.