LIlichess
Tournaments (Arena)

Create a new Arena tournament

Changed on

Create a public or private Arena tournament. This endpoint mirrors the form on https://lichess.org/tournament/new. You can create up to 12 public tournaments per day, or 24 private tournaments. A team battle can be created by specifying the teamBattleByTeam argument. Additional restrictions:

  • clockTime + clockIncrement > 0
  • 15s and 0+1 variant tournaments cannot be rated
  • Clock time in comparison to tournament length must be reasonable: 3 <= (minutes * 60) / (96 * clockTime + 48 * clockIncrement + 15) <= 150
post/api/tournament

Request

  • Base URL
    https://lichess.org
  • URL
    https://lichess.org/api/tournament
  • Auth
    OAuth 2
    Authorization code: https://lichess.org/oauth
    Token URL: https://lichess.org/api/token scopes: tournament:write

Request body application/x-www-form-urlencoded

namestring

The tournament name. Leave empty to get a random Grandmaster name

clockTime0 | 0.25 | 0.5 | 0.75 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 10 | 15 | 20 | 25 | 30 | 40 | 50 | 60 required

Clock initial time in minutes

clockIncrement0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 10 | 15 | 20 | 25 | 30 | 40 | 50 | 60 required

Clock increment in seconds

minutes20 | 25 | 30 | 35 | 40 | 45 | 50 | 55 | 60 | 70 | 80 | 90 | 100 | 110 | 120 | 150 | 180 | 210 | 240 | 270 | 300 | 330 | 360 | 420 | 480 | 540 | 600 | 720 required

How long the tournament lasts, in minutes

waitMinutes1 | 2 | 3 | 5 | 10 | 15 | 20 | 30 | 45 | 60

How long to wait before starting the tournament, from now, in minutes

startDateinteger

Timestamp (in milliseconds) to start the tournament at a given date and time. Overrides the waitMinutes setting

variant'standard' | 'chess960' | 'crazyhouse' | 'antichess' | 'atomic' | 'horde' | 'kingOfTheHill' | 'racingKings' | 'threeCheck' | 'fromPosition'
ratedboolean

Games are rated and impact players ratings

positionstring

Custom initial position (in X-FEN). Variant must be standard, fromPosition, or chess960 (if a valid 960 starting position), and the game cannot be rated.

berserkableboolean

Whether the players can use berserk. Only allowed if clockIncrement <= clockTime * 2

streakableboolean

After 2 wins, consecutive wins grant 4 points instead of 2.

hasChatboolean

Whether the players can discuss in a chat

descriptionstring

Anything you want to tell players about the tournament

passwordstring

Make the tournament private, and restrict access with a password. You can also generate user-specific entry codes based on this password.

teamBattleByTeamstring

Set the ID of a team you lead to create a team battle. The other teams can be added using the team battle edit endpoint.

conditions.teamMember.teamIdstring

Restrict entry to members of a team. The teamId is the last part of a team URL, e.g. https://lichess.org/team/coders has teamId = coders. Leave empty to let everyone join the tournament. Do not use this to create team battles, use teamBattleByTeam instead.

conditions.minRating.rating1000 | 1100 | 1200 | 1300 | 1400 | 1500 | 1600 | 1700 | 1800 | 1900 | 2000 | 2100 | 2200 | 2300 | 2400 | 2500 | 2600

Minimum rating to join. Leave empty to let everyone join the tournament.

conditions.maxRating.rating2200 | 2100 | 2000 | 1900 | 1800 | 1700 | 1600 | 1500 | 1400 | 1300 | 1200 | 1100 | 1000 | 900 | 800

Maximum rating to join. Based on best rating reached in the last 7 days. Leave empty to let everyone join the tournament.

conditions.nbRatedGame.nb0 | 5 | 10 | 15 | 20 | 30 | 40 | 50 | 75 | 100 | 150 | 200

Minimum number of rated games required to join.

conditions.allowListstring

Predefined list of usernames that are allowed to join, separated by commas. If this list is non-empty, then usernames absent from this list will be forbidden to join. Adding %titled to the list additionally allows any titled player to join. Example: thibault,german11,%titled

conditions.botsboolean

Whether bots are allowed to join the tournament.

conditions.accountAge1 | 3 | 7 | 14 | 30 | 60 | 90 | 180 | 365 | 730 | 1095

Minium account age in days required to join.

Example request

{
  "clockTime": 2,
  "clockIncrement": 1,
  "minutes": 60
}

Response

The Arena tournament has been successfully created.

idstring required
fullNamestring required
ratedboolean
berserkableboolean
onlyTitledboolean
minutesinteger
createdBystring
systemstring
secondsToStartinteger
secondsToFinishinteger
isFinishedboolean
isRecentlyFinishedboolean
pairingsClosedboolean
startsAtstring int64
nbPlayersinteger required
allowListstring[]

List of usernames allowed to join the tournament

hasMaxRatingboolean
botsAllowedboolean
minAccountAgeInDaysinteger
descriptionstring
variantstring
myUsernamestring

Changes