Tournaments
The Tournaments API for organizations, tournaments, stages, matches, teams, enrollments, free agents and standings, including the scopes that govern it.
The Tournaments API runs competitions for your players: you create an organization, create tournaments under it, take enrollments, generate the bracket or group stages, record match results and read standings. Everything you create belongs to your account, and no other tenant can see it.
Tournament routes have no /v1 prefix. You call /tournaments, /teams, /enrollments,
/matches/:matchId/result and so on directly on the Tournaments API base URL
($TOURNAMENT_API_URL in the samples).
The resources
| Resource | What it is | Identified by |
|---|---|---|
| Organization | The owner of your tournaments and teams, for example a league, a brand or a community. Every tournament and team belongs to one. | organizationId |
| Tournament | One competition, with its capacity, registration window, optional check-in and waitlist, schedule and lifecycle policy. | slug (generated from the name) |
| Stage | A phase of play in one format: single_elimination, double_elimination, round_robin, swiss or free_for_all. A stage composition chains a group stage into a final stage. | stageId |
| Match | One pairing inside a stage. Matches move through dormant, pending, ready, playing and completed. | matchId |
| Team | A named roster owned by an organization, used in team tournaments. | teamId |
| Enrollment | One entrant (a player or a team) in one tournament. | enrollmentId |
| Free-agent request | A player without a team asking to be picked up in a team tournament. | requestId |
| Standing | One entrant's computed record in a stage or group: played, wins, losses, draws, points, rank and the tiebreakers applied. | read per tournament |
Players are identified in tournaments by an entrant identity: mode is saas (a player known
to Tanitar, by principalId) or opaque (your own stable externalId), plus an optional
displayName. A tournament declares which modes it accepts in identityModes.
Organization ownership
Tournament, stage, match, team and enrollment routes check that the resource belongs to an
organization your credential may act for. With an API key, those are the active organizations
whose ownerPrincipalId is that key's id. Set ownerPrincipalId to the id of the API key your
integration uses when you create the organization, or requests on its tournaments are refused with
403 and errorCode ACCESS_RESOURCE_FORBIDDEN. Administrators in the dashboard see every
organization of your account.
Scopes
| Scope | Grants |
|---|---|
organizations:read | List and read organizations. |
organizations:mutate | Create, update, disable, enable and delete organizations. |
tournaments:read | Read tournaments, stages, stage compositions, matches, teams and entrants; preview stage rounds. |
tournaments:mutate | Create and run tournaments and stages; manage teams, enrollments, check-in and free-agent requests; edit matches. |
participants:mutate | Act for an entrant: mark a match ready, submit, edit and withdraw evidence. |
results:read | Read result history, evidence, evidence media links and standings. |
results:mutate | Report, correct and revert results; review evidence; purge evidence media. |
See API keys and scopes to issue a key with these scopes.
Conventions
- Responses are wrapped:
{ "success": true, "responseType": "SUCCESS", "data": ... }. A refusal uses the shared error envelope with a stableerrorCodesuch asTOURNAMENT_STATE_INVALIDorRESULT_STALE. - Every mutation requires an
Idempotency-Keyheader. A retry with the same key returns the original answer. See Idempotency. - Lists of tournaments, stages, stage compositions, matches and entrants take
cursorandlimit(default 50, maximum 100) and return{ items, nextCursor }; passnextCursorback ascursoruntil it isnull. Organizations use the same pair. Standings, evidence and result revisions return the whole set without pagination. See Pagination. - Concurrent writes are guarded by revisions. Match edits, results and readiness take an
expectedRevision; a stale one is refused with409so you can re-read and retry. - Rate limits apply per plan and per rate class (
read,mutation). See Rate limits.
Events
Every state change in a tournament is published as an event your webhook endpoint can receive:
tournament.tournament.published, tournament.enrollment.confirmed,
tournament.match.result-applied, tournament.standings.updated,
tournament.tournament.completed, tournament.tournament.placements-finalized and more. See the
event catalog.
A typical flow
flowchart LR A[Create organization] --> B[Create tournament] B --> C[Publish] C --> D[Players enroll] D --> E[Close registration] E --> F[Close check-in] F --> G[Generate stages] G --> H[Start] H --> I[Report results] I --> J[Complete]
Stages can be generated once the tournament is published, and must exist before it starts. A tournament that pays prizes pairs with Rewards: a completed tournament finalizes its placements, and awards bound to those placements are granted automatically.