Fizzer: Created page with "War.app has two APIs for public tournaments: * '''CreatePublicTournament''' creates a public tournament. * '''ForwardPublicTournamentInvites''' invites players to a public tournament you created. Together, they let a program run its own tournament series. For example, a program could create a tournament each week and invite everyone on a list. Like the Create game API, these APIs are restricted to War.app members, and only work with your API token...."

2026-11-02T10:39:51Z

Created page with "War.app has two APIs for public tournaments: * '''CreatePublicTournament''' creates a public tournament. * '''ForwardPublicTournamentInvites''' invites players to a public tournament you created. Together, they let a program run its own tournament series. For example, a program could create a tournament each week and invite everyone on a list. Like the Create game API, these APIs are restricted to War.app members, and only work with your API token...."

New page

War.app has two APIs for public tournaments:
* '''CreatePublicTournament''' creates a public tournament.
* '''ForwardPublicTournamentInvites''' invites players to a public tournament you created.

Together, they let a program run its own tournament series. For example, a program could create a tournament each week and invite everyone on a list.

Like the [[Create game API]], these APIs are restricted to War.app [[Membership|members]], and only work with your API token.

They only work with public tournaments, which appear on the Open Tournaments list for anyone to join. Private tournaments aren't supported. The APIs enforce the same rules as the tournament creation pages on the website. Anything they create could also have been created there.

==Calling the APIs==

To call either API, POST JSON to its URL. Every request needs these two fields:
* '''hostEmail''' / '''hostAPIToken''': these identify you. You can get your API token from the [[Get API Token API]].

Every response is a JSON object with a '''termsOfUse''' field. If the call fails, the response also has an '''error''' field describing what went wrong. That's either a message, or the name of an error such as <code>InsufficientCoins</code>. For example:

{
"termsOfUse": "Please use this API responsibly, ...",
"error": "Public tournaments must be at least 8 players"
}

When a call fails, nothing is changed.

==CreatePublicTournament==

POST to https://www.war.app/API/CreatePublicTournament. You'll be the tournament's creator, exactly as if you'd created it through the UI. You pay its creation cost in coins (see [[#Coins|Coins]]).

Example:

{
"hostEmail": "your@email.com",
"hostAPIToken": "yourApiToken",
"tournamentName": "Weekly 1v1 (max 50 chars)",
"description": "Shown on the tournament's page",
"templateID": 1234,
"type": "SingleElimination",
"teamSize": 1,
"teamsPerGame": 2,
"numberOfRounds": 4,
"canForwardInvites": true,
"entryFee": 10,
"extraCoins": 0,
"startInMinutes": 60,
"settings": { ... }
}

{| class="wikitable"
! Field !! Required !! Description
|-
| tournamentName || Yes || The tournament's name. Maximum 50 characters.
|-
| description || No || The tournament's description. It's the same as the PersonalMessage setting. If you also give PersonalMessage in '''settings''', that's used instead.
|-
| templateID || No || The ID of the template whose settings the tournament's games use. If you leave it out, the "Normal Game" template is used.
|-
| settings || No || Settings that override the template's, the same way as in the [[Create game API]]. To see a full list of settings, use the [[Query game API]] with GetSettings=true.
|-
| type || Yes || <code>SingleElimination</code> or <code>DoubleElimination</code>. Public tournaments can't be round robin.
|-
| teamSize || Yes || How many players are on each team. Use 1 for a tournament without teams.
|-
| teamsPerGame || Only for SingleElimination || How many teams play in each game. Double elimination games always have 2 teams, so this is ignored for DoubleElimination.
|-
| numberOfRounds || Yes || How many rounds the tournament has, at least 2. The number of players is teamsPerGame to the power of numberOfRounds, times teamSize. For example, 4 rounds of 1v1 is 2<sup>4</sup> × 1 = 16 players.
|-
| canForwardInvites || Yes || <code>true</code> to let players in the tournament invite others.
|-
| entryFee || No || The coins each player pays to join, from 0 to 2,000. Defaults to 0.
|-
| extraCoins || No || Coins you add to the prizes, from 0 to 50,000. Defaults to 0.
|-
| startInMinutes || Yes || How many minutes from now the tournament starts. See [[#Start time|Start time]].
|}

On success, the response includes the new tournament's ID, as a string:

{
"termsOfUse": "...",
"tournamentID": "123456"
}

When the tournament is created, it's also announced in the global chat, the same as when you create one on the website.

===Requirements===

The tournament must meet the same requirements as on the website's tournament creation page:
* You must have unlocked tournaments.
* It must have between 8 and 512 players.
* Each game can have at most 40 players (teamSize × teamsPerGame).
* The template and settings must be valid for a tournament on the map they use. For example, the map must be public, and must be big enough for each game's players.
* In real-time tournaments, the boot time must be at least 2 minutes.

===Boot times===

Tournaments have one boot time, like on the website's boot time step. The tournament uses the direct boot time from the template or settings:
* The auto boot time is set to the same value.
* If the initial bank is used, the banking boot time is set to 0. Otherwise, it isn't used.
You don't need to give the auto boot or banking boot times. Any values you give for them are replaced.

===Start time===

'''startInMinutes''' must be:
* For real-time tournaments: at least 1, and at most 120.
* For multi-day tournaments: at least 5, and at most 1440 (one day).

===Coins===

Public tournaments are always coin tournaments. You pay a creation cost when the tournament is created. If you don't have enough coins, the call fails with <code>InsufficientCoins</code>. The cost is the same as on the website. It's currently:
* the entry fee, plus
* the number of players divided by 4, rounded up, plus
* the extra coins, plus
* 3 more coins if the entry fee is 0.

The prizes are worked out the same way as for tournaments created on the website.

==ForwardPublicTournamentInvites==

POST to https://www.war.app/API/ForwardPublicTournamentInvites to invite players to a public tournament. Each invited player gets a notification, as when you invite someone from the tournament's page.

Example:

{
"hostEmail": "your@email.com",
"hostAPIToken": "yourApiToken",
"tournamentID": 123456,
"players": [ "66553413", "134314314", "someone@example.com" ]
}

{| class="wikitable"
! Field !! Required !! Description
|-
| tournamentID || Yes || The ID of the tournament, such as one returned by CreatePublicTournament.
|-
| players || Yes || The players to invite. Each is either an invite token or the e-mail address of a War.app account. Players can find their invite token at https://www.war.app/InviteToken; it's also the number in the address bar when you view a player's profile. You can invite 1 to 100 players per call.
|}

On success, the response says how many players the request named:

{
"termsOfUse": "...",
"success": "",
"invited": 3
}

If the same player appears twice, such as by both their invite token and their e-mail address, they're only counted once. Players who are already in the tournament aren't invited again, but they are counted.

===Requirements===

* You must be the tournament's creator. This works even if the tournament doesn't let players forward invites (see '''canForwardInvites''' above).
* The tournament must be public, and mustn't have started yet.
* Every player must have unlocked tournaments. Open seats and AI players can't be used.
* You can't invite a player who has you on their block list.
* The total number of players invited to a tournament is limited to 13 times its number of players, up to 2,000. The call fails with <code>TooManyPlayersInvitedToTournament</code> if it would go over.

If any player in the list can't be invited, the call fails and nobody from the list is invited. In most cases, the error says which player caused it.

==See Also==

* [[API]]
* [[Create game API]]
* [[Get API Token API]]
* [[Validate invite token API]]

[[Category:API]]

Public Tournament API - Revision history