Skip to main content

Documentation Index

Fetch the complete documentation index at: https://teambattles.gg/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Interactive Endpoints

Try out the API directly from the docs:

User Matches

Retrieve matches where you’re on the roster

Team Matches

Retrieve matches for a specific team

Organization Matches

Retrieve matches for all teams in an organization

Twitch Global Badges

Access global Twitch badge data

Twitch Channel Badges

Access channel-specific Twitch badge data

​
Captain Score Endpoints

These endpoints allow team captains to submit and manage scores.
MethodEndpointDescriptionPermission
POST/matches/{matchId}/scoresSubmit a map scorematches.team_matches: read-write
PATCH/matches/{matchId}/scoresConfirm opponent’s scorematches.team_matches: read-write
GET/matches/{matchId}/scoresGet all map scoresmatches.team_matches: read

​
Game Developer Endpoints

These endpoints are for approved game developers.

​
Score Submission

MethodEndpointDescriptionPermission
POST/game/matches/{matchId}/scoresSubmit verified scoregame.scores: write

​
Match Lifecycle

MethodEndpointDescriptionPermission
POST/game/matchesList matches (JSON body with gameId)game.lifecycle: read
GET/game/matches/{matchId}Get match detailsgame.lifecycle: read
GET/game/matches/{matchId}/rostersGet match rostersgame.lifecycle: read
GET/game/matches/{matchId}/statusGet match statusgame.lifecycle: read
PATCH/game/matches/{matchId}/statusUpdate match statusgame.lifecycle: read-write

​
Player Stats

MethodEndpointDescriptionPermission
POST/game/matches/{matchId}/player-statsSubmit player stats for a mapgame.scores: write

​
Common Response Codes

StatusDescription
200Success
201Created
400Bad request - invalid parameters
401Unauthorized - missing or invalid API key
403Forbidden - insufficient permissions
404Resource not found
409Conflict - duplicate or invalid state
429Rate limited
500Internal server error

​
Error Format

All errors follow a consistent format: 
{
	"error": "ERROR_CODE",
	"message": "Human-readable description"
}

​
Pagination

The v1 API is mid-migration and currently exposes two pagination envelope shapes. Check each endpoint’s reference page for its exact response shape.

​
Native envelope (match listing endpoints)

The three match listing endpoints use Convex’s native pagination envelope: Request fields: numItems (page size, default 25) and cursor (opaque string from the previous response, or omit/null for the first page). Response shape: { page, isDone, continueCursor }. Iterate page for results, check isDone to know when you’ve reached the end, and pass continueCursor as cursor in the next request. 
POST /api/v1/user/matches
Content-Type: application/json

{
  "numItems": 25,
  "cursor": "g2wAAAACYQJhAmo="
}

​
Legacy envelope (all other v1 endpoints)

Most remaining v1 paginated endpoints still wrap results in a legacy envelope: { matches, pagination: { cursor, hasMore }, timestamp }. Pass cursor (and typically limit) in the request body to get the next page. This shape will be migrated to the native envelope in a follow-up release. 
POST /api/v1/game/matches
Content-Type: application/json

{
  "gameId": "call_of_duty_black_ops_7",
  "cursor": "25",
  "limit": 25
}