Skip to main content
POST
/
game
/
matches
/
create
curl -X POST https://teambattles.gg/api/v1/game/matches/create \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c-unique-per-create" \
  -d '{"creatorTeamId":"team_abc","acceptedTeamId":"team_xyz","gameModeId":"search_and_destroy","bestOf":5,"teamSize":4,"platform":"CROSSPLAY","inputDevice":"ALL","region":"NONE","mapSelectionType":"COMPETITIVE","mapPreferenceMode":"PREFERRED"}'

{
  "success": true,
  "matchId": "<string>",
  "timestamp": "<string>"
}

​
Permission Required

This endpoint requires the game.lifecycle permission with read-write access. Your API key must be a game-developer key bound to a game; the match is created for that bound game (the game is never a request field).

​
Access / Membership Rules

Both creatorTeamId and acceptedTeamId must be active teams in your bound game. A key bound to a different game, or a non-developer key, receives a 403 error_game_scope_mismatch.

​
Idempotency

Supply an optional Idempotency-Key request header to make retries safe: an identical key + body replays the original response, while the same key with a different body returns 409 error_idempotency_key_conflict.

​
What’s Returned

Returns { "success": true, "matchId": "<id>", "timestamp": "<ISO-8601>" }. The created match is ACCEPTED and PUBLISHED.

​
Request Body

FieldTypeRequiredDescription
creatorTeamIdstringYesActive team in your game that creates the match.
acceptedTeamIdstringYesActive opposing team in your game.
gameModeIdstringYesGame mode identifier (e.g. search_and_destroy).
bestOfnumberYesSeries length: one of 1, 3, 5, 7.
teamSizenumberYesPlayers per team (validated against the game’s min/max).
platformenumYesPC / XBOX / PLAYSTATION / CONSOLE_ONLY / CROSSPLAY.
inputDeviceenumYesALL / CONTROLLER / KB_M.
regionenumYesNONE / NA_EAST / NA_WEST / EU / ASIA / OCEANIA / SOUTH_AMERICA / MIDDLE_EAST / AFRICA.
mapSelectionTypeenumYesCOMPETITIVE / FLEX.
mapPreferenceModeenumYesPREFERRED / VETO / MANUAL.
Only selectedMaps, selectedObjectives, and scheduledAt are optional; they are rendered from the schema in the playground below.
curl -X POST https://teambattles.gg/api/v1/game/matches/create \
  -H "Authorization: Bearer tb_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c-unique-per-create" \
  -d '{"creatorTeamId":"team_abc","acceptedTeamId":"team_xyz","gameModeId":"search_and_destroy","bestOf":5,"teamSize":4,"platform":"CROSSPLAY","inputDevice":"ALL","region":"NONE","mapSelectionType":"COMPETITIVE","mapPreferenceMode":"PREFERRED"}'

Authorizations

​
Authorization
string
header
required

Send your API key as: Authorization: Bearer tb_

Body

application/json

Request body for creating a two-sided game-originated match. The match is created ACCEPTED + PUBLISHED for the key's bound game. Supports an optional Idempotency-Key header for safe retries.

​
creatorTeamId
string
required

ID of the creating team. Must belong to the key's bound game.

​
acceptedTeamId
string
required

ID of the opposing team. Required - game-originated matches are two-sided. Must belong to the key's bound game.

​
gameModeId
string
required

Game mode identifier (e.g. search_and_destroy).

​
bestOf
enum<number>
required

Number of maps in the series. One of 1, 3, 5, or 7.

Available options:
1,
3,
5,
7
​
teamSize
number
required

Players per team (validated against the game's min/max).

​
platform
enum<string>
required

Match platform (e.g. CROSSPLAY).

Available options:
PC,
XBOX,
PLAYSTATION,
CONSOLE_ONLY,
CROSSPLAY
​
inputDevice
enum<string>
required

Allowed input device (e.g. ALL).

Available options:
ALL,
CONTROLLER,
KB_M
​
region
enum<string>
required

Match region (e.g. NONE).

Available options:
NONE,
NA_EAST,
NA_WEST,
EU,
ASIA,
OCEANIA,
SOUTH_AMERICA,
MIDDLE_EAST,
AFRICA
​
mapSelectionType
enum<string>
required

Map selection type (COMPETITIVE or FLEX).

Available options:
COMPETITIVE,
FLEX
​
mapPreferenceMode
enum<string>
required

Map preference mode (PREFERRED, VETO, or MANUAL).

Available options:
PREFERRED,
VETO,
MANUAL
​
selectedMaps
string[]

Optional pre-selected map IDs.

​
selectedObjectives
string[]

Optional pre-selected objective IDs.

​
scheduledAt
number

Optional scheduled start time (epoch ms).

Response

The created match's ID.

Result of a successful game-originated match creation.

​
success
boolean
required
​
matchId
string
required

ID of the newly created match.

​
timestamp
string
required

Server response time (ISO 8601).