LIlichess
Tournaments (Swiss)

Create a new Swiss tournament

Create a Swiss tournament for your team. This endpoint mirrors the Swiss tournament form from your team pagee. You can create up to 12 tournaments per day. Additional restrictions:

  • clock.limit + clock.increment > 0
  • 15s and 0+1 variant tournaments cannot be rated
post/api/swiss/new/{teamId}

Request

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

Path parameters

teamIdstring required

ID of the team

Request body application/x-www-form-urlencoded

namestring

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

clock.limit0 | 15 | 30 | 45 | 60 | 90 | 120 | 180 | 240 | 300 | 360 | 420 | 480 | 600 | 900 | 1200 | 1500 | 1800 | 2400 | 3000 | 3600 | 4200 | 4800 | 5400 | 6000 | 6600 | 7200 | 7800 | 8400 | 9000 | 9600 | 10200 | 10800 required

Clock initial time in seconds

clock.incrementinteger required

Clock increment in seconds

nbRoundsinteger required

Maximum number of rounds to play

startsAtinteger

Timestamp in milliseconds to start the tournament at a given date and time. By default, it starts 10 minutes after creation.

roundInterval-1 | 5 | 10 | 20 | 30 | 45 | 60 | 120 | 180 | 300 | 600 | 900 | 1200 | 1800 | 2700 | 3600 | 86400 | 172800 | 604800 | 99999999

How long to wait between each round, in seconds. Set to 99999999 to manually schedule each round from the tournament UI. If empty or -1, a sensible value is picked automatically.

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

Custom initial position (in X-FEN). Variant must be standard and the game cannot be rated.

descriptionstring

Anything you want to tell players about the tournament

ratedboolean

Games are rated and impact players ratings

passwordstring

Make the tournament private and restrict access with a password.

forbiddenPairingsstring

Usernames of players that must not play together. Two usernames per line, separated by a space.

manualPairingsstring

Manual pairings for the next round. Two usernames per line, separated by a space. Example:

PlayerA PlayerB
PlayerC PlayerD

To give a bye (1 point) to a player instead of a pairing, add a line like so:

PlayerE 1

Missing players will be considered absent and get zero points.

chatFor0 | 10 | 20 | 30

Who can read and write in the chat.

  • 0 = No-one
  • 10 = Only team leaders
  • 20 = Only team members
  • 30 = All Lichess players
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.nbinteger

Minimum number of rated games required to join.

conditions.playYourGamesboolean

Only let players join if they have played their last swiss game. If they failed to show up in a recent swiss event, they won't be able to enter yours. This results in a better swiss experience for the players who actually show up.

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

Example request

{
  "clock.limit": 300,
  "clock.increment": 1
}

Response

The Swiss tournament was successfully created.

idstring required
createdBystring required
startsAtstring required
namestring required
variantstring required
roundnumber required
nbRoundsnumber required
nbPlayersnumber required
nbOngoingnumber required
status'created' | 'started' | 'finished' required

The current state of the swiss tournament

ratedboolean required

Changes

No recorded changes to this operation across all 16 revisions of this API.