Tournaments
How tournaments work in Tournament Suite — lifecycle, structure, and key API operations.
A tournament is the central resource in Tournament Suite. It defines the competitive event, its format, its participants, and its schedule.
Tournament lifecycle
Tournaments move through the following states:
DRAFT → REGISTRATION_OPEN → REGISTRATION_CLOSED → IN_PROGRESS → COMPLETEDSUSPENDED and CANCELLED can interrupt this flow at most points before completion.
| Status | Description |
|---|---|
DRAFT | Tournament is being configured; not visible to the public |
UPCOMING | Tournament is scheduled but registration has not opened yet |
REGISTRATION_OPEN | Players can register |
REGISTRATION_CLOSED | Registration period has ended; organizer finalizes check-in and the bracket |
IN_PROGRESS | Tournament is in progress; matches are being played |
SUSPENDED | Play is temporarily paused (organizer or admin action) |
CANCELLED | Tournament was cancelled; terminal state |
COMPLETED | All matches are resolved; final results are locked; terminal state |
POST /tournaments/:id/publish transitions a tournament directly from DRAFT to REGISTRATION_OPEN — there is no intermediate "published but not open" state. POST /tournaments/:id/suspend (and its organizer-facing alias POST /tournaments/:id/pause) move a tournament to SUSPENDED. POST /tournaments/:id/cancel moves any non-terminal tournament to CANCELLED.
Once a tournament moves to IN_PROGRESS, structural settings (format, team size, stage configuration) are locked.
Structure
A tournament contains one or more stages. Each stage has a format. The API accepts lowercase snake_case format values, for example:
| Format | Value | Description |
|---|---|---|
| Single Elimination | single_elimination | Losers are immediately eliminated |
| Double Elimination | double_elimination | Losers drop to a losers bracket and get a second chance; the bracket routes losers through to a grand final against the winners-bracket champion |
| Round Robin | round_robin | Every participant plays every other participant |
| Swiss | swiss | Participants are paired by current score each round |
| Group Stage | group_stage | Pool stage producing ranked qualifiers |
These are the most commonly used formats. Tournament Suite also supports additional specialized formats (battle royale, ladder, league, gauntlet, and others) for non-bracket competitive structures.
Stages run sequentially. Participants who advance from Stage 1 are automatically seeded into Stage 2. Multi-stage structure isn't set at tournament creation — it's configured afterward through the structure/bracket workspace.
Bracket sizing and the reserve bench
Brackets are generated sized to the tournament's approved entrants only. If more players register than the bracket needs, the surplus is placed on a reserve bench rather than rejected outright. Organizers can move a participant to the reserve bench or promote a reserved participant into the approved roster (capacity permitting) before the bracket is finalized.
Key endpoints
List tournaments
GET /api/v1/tournaments?status=REGISTRATION_OPEN&page=1&limit=20Get a tournament
GET /api/v1/tournaments/:idResponse includes full tournament details, current status, stage configuration, and participant counts.
Create a tournament
POST /api/v1/tournaments
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
"name": "Summer Open 2026",
"game": "Counter-Strike 2",
"format": "single_elimination",
"type": "team",
"maxParticipants": 64,
"isPublic": true,
"allowSpectators": true,
"timezone": "UTC",
"startDate": "2026-08-01T00:00:00Z",
"registrationDeadline": "2026-07-30T00:00:00Z"
}type sets the participant structure (individual, duo, team, squad, or mixed) and determines the valid team size range — there is no separate teamSize field. game is a free-text label; to associate a canonical discipline instead, pass disciplineId with the discipline's UUID. Multi-stage structure (for example a group stage followed by playoffs) is added after creation via the structure/bracket workspace, not in this request body.
Start a tournament
POST /api/v1/tournaments/:id/startStarting a tournament closes registration, generates the bracket, and seeds participants. After this point, the tournament is IN_PROGRESS.
Check-in
Before a tournament starts, organizers can require participants to check in. Check-in is configured with an enable/deadline window, an optional late-allowance grace period, and support for bulk check-in and reminders. Check-in status gates who counts toward the bracket — closing registration and planning matches accounts for who has checked in, and no-shows can be recorded automatically.
Brackets and seeding
Once a tournament starts, each stage generates its bracket or group table. You can retrieve the bracket at any point:
GET /api/v1/tournaments/:id/bracketThe response includes the full match tree with participant assignments, scores, and advancement paths.
Seeding can be generated, previewed, and applied ahead of the bracket being finalized, and adjusted afterward with a bulk seed update on the tournament's seeds.
Standings and prizes
Once matches are underway, you can retrieve computed standings for a tournament (including tiebreaker values where the format uses them) and tournament-level statistics. On completion, any configured prize pool is distributed according to the tournament's prize configuration, and winners can claim their prize assignments.
Related resources
- Participants — who is in the tournament
- Matches — individual games within a stage
- Webhooks — get notified when tournament state changes
Was this helpful?