My Matches

Create a match

Changed on

Creates a new match as the personal API key owner. The owner must be a captain, co-captain, or org owner of the creator team and the active roster must be members of that team. League and challenge rules are enforced exactly as in the web app. Requires matches.user_matches:read-write and API writes access. Supports an optional Idempotency-Key header for safe retries.

post/matches/create

Request

  • Base URL
    https://teambattles.gg/api/v1
  • URL
    https://teambattles.gg/api/v1/matches/create
  • Auth
    HTTP bearer

Request body

teamIdstring required

Creator team ID. The owner must be a captain, co-captain, or org owner of it.

gameIdstring required

Game ID for the match.

gameModeIdstring required

Game mode ID (client-side definition).

matchType'XP_ONLY' | 'WAGER' required

Match type.

mapSelectionType'COMPETITIVE' | 'FLEX' required

Map selection type.

mapPreferenceMode'PREFERRED' | 'VETO' | 'MANUAL' required

Map preference mode.

teamSizeinteger required

Players per team.

bestOfinteger required

Series length (best of N).

platform'PC' | 'XBOX' | 'PLAYSTATION' | 'CONSOLE_ONLY' | 'CROSSPLAY'

Platform (defaults to CROSSPLAY).

inputDevice'ALL' | 'CONTROLLER' | 'KB_M'

Input device (defaults to ALL).

region'NONE' | 'NA_EAST' | 'NA_WEST' | 'EU' | 'ASIA' | 'OCEANIA' | 'SOUTH_AMERICA' | 'MIDDLE_EAST' | 'AFRICA'

Region (defaults to NONE).

scheduledAtnumber

Scheduled start (epoch ms).

wagerAmountnumber

Wager amount (WAGER matches only).

selectedMapsstring[]

Selected map IDs.

selectedObjectivesstring[]

Selected objective IDs.

gameSpecificOptionsobject

Game-specific options.

lockedRulesobject

Locked rule flags.

notesstring

Optional match notes.

publishStatus'DRAFT' | 'PUBLISHED' | 'ARCHIVED'

Publish status (defaults to DRAFT).

activeRosterstring[] required

Active roster user IDs (must be creator-team members).

isChallengeboolean

Create as a direct challenge to another team.

challengedTeamIdstring

Challenged team ID (required when isChallenge is true).

leagueIdstring

League ID for a league match.

Response

The match was created.

successtrue required
matchIdstring required
timestampstring required

Changes