Skip to main content
POST
/
teams
/
{identifier}
/
matches
curl -X POST https://teambattles.gg/api/v1/teams/Team_Alpha/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"excludeStatuses": ["CANCELLED", "FORFEITED"], "numItems": 25}'

{
  "page": [
    {
      "id": "<string>",
      "game": {
        "id": "<string>",
        "nameKey": "<string>"
      },
      "gameMode": "<string>",
      "creatorTeam": {
        "id": "<string>",
        "name": "<string>",
        "tag": "<string>"
      },
      "acceptedTeam": {
        "id": "<string>",
        "name": "<string>",
        "tag": "<string>"
      },
      "scheduledAt": "2023-11-07T05:31:56Z",
      "startedAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "bestOf": 123
    }
  ],
  "isDone": true,
  "continueCursor": "<string>"
}

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.

curl -X POST https://teambattles.gg/api/v1/teams/Team_Alpha/matches \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"excludeStatuses": ["CANCELLED", "FORFEITED"], "numItems": 25}'

​
Permission Required

This endpoint requires the matches.team_matches permission on your API key.

​
Membership Required

You must be an active member of the team to access its matches. If you’re not a member, you’ll receive a 403 error with code error_team_membership_required.

​
Team Identifier

The {identifier} path parameter accepts either:
  • Team ID: The Convex document ID (e.g., jh7abc123def456)
  • Team Slug: The URL-friendly team name (e.g., Team_Alpha)
The slug is derived from the team name by replacing spaces with underscores.

​
Filtering Options

​
Status Filtering

Filter matches by their status:
  • includeStatuses: Only return matches with these statuses (takes precedence)
  • excludeStatuses: Return all matches except those with these statuses

​
Date Filtering

Filter by scheduled or creation dates using ISO 8601 format:
  • scheduledAfter / scheduledBefore: Filter by scheduled match time
  • createdAfter / createdBefore: Filter by when the match was created

​
Other Filters

  • gameId: Filter by a specific game
  • opponentId: Filter by opponent team (accepts team ID or slug)

​
Pagination

Results are paginated with a default of 25 matches per page (maximum 100).

​
Request Fields

ParameterTypeDescription
numItemsnumberNumber of items per page, 1-100, default 25
cursorstringOpaque cursor string from a prior response (optional)

​
Response Fields

FieldTypeDescription
pagearrayArray of matches for this page
isDonebooleantrue when there are no more pages to fetch
continueCursorstringPass back as cursor on the next request
Example response envelope: 
{
	"page": [],
	"isDone": false,
	"continueCursor": "eyJpZCI6Im1hdGNoXzEyMyIsInRzIjoxNzA0MDY3MjAwfQ=="
}

​
Errors

CodeHTTP StatusWhen
error_api_key_required401Missing Authorization header
error_api_key_invalid401API key is unknown, revoked, or expired
error_api_key_permission_denied403The key does not hold matches.team_matches: read
error_team_membership_required403You are not an active member of the requested team
error_invalid_num_items400numItems is outside the allowed 1-100 range
error_invalid_limit400Reserved for limit-style page sizes (registry-level error code)
error_invalid_cursor400cursor is malformed or no longer valid
error_invalid_date_format400One of the scheduled*/created* filters is not ISO 8601
error_team_not_found404The {identifier} or opponentId could not be resolved
error_internal500Unhandled server error - retry or contact support

​
Common Use Cases

​
Get Active Team Matches

{
	"excludeStatuses": ["PENDING", "COMPLETED", "CANCELLED", "FORFEITED"],
	"numItems": 25
}

​
Get Matches Against a Specific Opponent

{
	"opponentId": "Team_Beta",
	"includeStatuses": ["COMPLETED"]
}

​
Get Upcoming Scheduled Matches

{
	"scheduledAfter": "2024-01-15T00:00:00Z",
	"includeStatuses": ["ACCEPTED", "READY"]
}

​
Get Match History for a Date Range

{
	"scheduledAfter": "2024-01-01T00:00:00Z",
	"scheduledBefore": "2024-03-31T23:59:59Z",
	"includeStatuses": ["COMPLETED", "FORFEITED"],
	"numItems": 100
}

Authorizations

​
Authorization
string
header
required

API key authentication. Generate an API key from Settings > Developer in the TeamBattles app. Format: tb_xxxxxxxx...

Path Parameters

​
identifier
string
required

Team ID or slug

Body

application/json

Optional filters and pagination options

​
includeStatuses
enum<string>[]

Only include matches with these statuses. Takes precedence over excludeStatuses.

Current status of a match

Available options:
PENDING,
ACCEPTED,
READY,
IN_PROGRESS,
COMPLETED,
CANCELLED,
DISPUTED,
FORFEITED
​
excludeStatuses
enum<string>[]

Exclude matches with these statuses. Ignored if includeStatuses is provided.

Current status of a match

Available options:
PENDING,
ACCEPTED,
READY,
IN_PROGRESS,
COMPLETED,
CANCELLED,
DISPUTED,
FORFEITED
​
gameId
string

Filter by game ID

​
scheduledAfter
string<date-time>

Filter to matches scheduled after this date (ISO 8601)

​
scheduledBefore
string<date-time>

Filter to matches scheduled before this date (ISO 8601)

​
createdAfter
string<date-time>

Filter to matches created after this date (ISO 8601)

​
createdBefore
string<date-time>

Filter to matches created before this date (ISO 8601)

​
opponentId
string

Filter by opponent team (ID or slug)

​
numItems
integer
default:25

Maximum number of matches to return (1-100)

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor from previous response (opaque Convex cursor string)

Response

Successful response

​
page
object[]
required
​
isDone
boolean
required
​
continueCursor
string
required