Skip to main content

​
Overview

Create a new arena tournament on Lichess. Arena tournaments use automatic pairing and allow players to join at any time during the tournament.
Requires authentication with OAuth token that has the tournament:write scope.

​
Endpoint

curl -X POST https://lichess.org/api/tournament \
  -H "Authorization: Bearer {token}" \
  -d "name=My Arena Tournament" \
  -d "clockTime=3" \
  -d "clockIncrement=2" \
  -d "minutes=45" \
  -d "startDate=1710000000000"

​
Authentication

Requires OAuth token with tournament:write scope: 
Authorization: Bearer lip_xxxxxxxxxxxx

​
Request Parameters

​
name
string
Tournament name (2-35 characters). Optional - defaults to your username or a random name
​
clockTime
number
required
Clock initial time in minutes (decimal allowed, e.g., 0.5 for 30 seconds)
​
clockIncrement
integer
required
Clock increment in seconds per move
​
minutes
integer
required
Tournament duration in minutes. Valid options: 20, 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
​
waitMinutes
integer
Delay before tournament starts (1-60 minutes). Default: 5. Omit for instant start if using startDate
​
startDate
integer
Timestamp in milliseconds for scheduled start. Cannot be more than 1 day in advance for non-verified accounts
​
variant
string
Chess variant. Options: standard, chess960, crazyhouse, antichess, atomic, horde, kingOfTheHill, racingKings, threeCheck. Default: standard
​
rated
boolean
Whether the tournament is rated. Default: true. Some variant/time control combinations cannot be rated
​
position
string
FEN string for custom starting position (thematic tournament). Only valid for standard variant
​
berserkable
boolean
Allow players to go berserk (halve clock for bonus points). Default: true. Not allowed if increment > time*2
​
streakable
boolean
Enable streak scoring. Default: true
​
hasChat
boolean
Enable tournament chat. Default: true
​
description
string
Tournament description text
​
password
string
Password required to join the tournament. Creates a private tournament

​
Entry Conditions

​
conditions.minRating.rating
integer
Minimum rating required to join (in the relevant perf type)
​
conditions.maxRating.rating
integer
Maximum rating allowed to join (in the relevant perf type)
​
conditions.nbRatedGame.nb
integer
Minimum number of rated games required in the relevant perf type
​
conditions.accountAge.nb
integer
Minimum account age in days
​
conditions.allowList
string
Comma-separated list of usernames allowed to join (creates an allow-list tournament)

​
Team Battle Parameters

​
teamBattleByTeam
string
Team ID to create a team battle tournament. You must be a team leader to use this
​
conditions.teamMember.teamId
string
Restrict tournament to members of a specific team

​
Response

Returns the created tournament object with all details:
​
id
string
8-character tournament ID
​
name
string
Tournament name
​
status
integer
Always 10 (created) for newly created tournaments
​
createdBy
string
Your user ID
​
startsAt
integer
Tournament start timestamp in milliseconds
​
finishesAt
integer
Tournament end timestamp in milliseconds
​
nbPlayers
integer
Number of players (initially 0 or 1 if auto-joined)

​
Example Response

{
  "id": "QITRjufu",
  "createdBy": "your_username",
  "startsAt": 1709743500000,
  "name": "My Arena Tournament",
  "clock": {
    "limit": 180,
    "increment": 2
  },
  "minutes": 45,
  "status": 10,
  "nbPlayers": 1,
  "variant": {
    "key": "standard",
    "name": "Standard"
  },
  "rated": true,
  "perf": {
    "key": "blitz",
    "name": "Blitz"
  },
  "finishesAt": 1709746200000
}

​
Validation Rules

​
Clock Validation

  • Total time must be > 0 (clockTime + clockIncrement > 0)
  • For bot tournaments, time control must be bot-compatible (≥ 2+1)
  • Berserk disabled if increment > clockTime * 2

​
Duration Validation

  • Minimum games per player must be ≥ 3
  • Maximum games per player must be ≤ 150
  • Calculated as: (minutes * 60) / estimatedGameSeconds

​
Rating Validation

  • Cannot be rated if using custom position (unless it’s a known thematic opening)
  • 15s and 0+1 variant games cannot be rated

​
Rate Limits

Tournament creation is rate-limited based on:
  • User status (verified, streamer, titled player)
  • Tournament visibility (private vs public)
  • IP address
Typical limits:
  • Verified users: 2 tournaments per hour
  • Regular users: 20 tournaments per hour (higher cost per creation)
  • Private tournaments have lower rate limit cost

​
Error Responses

{
  "error": "Invalid clock"
}

​
Best Practices

  • Use descriptive tournament names
  • Set appropriate wait times (5-10 minutes recommended)
  • Consider time zones when scheduling tournaments
  • For team battles, coordinate with team leaders
  • Test time controls to ensure sufficient game count

​
Source Code Reference

Implementation can be found in:
  • app/controllers/Tournament.scala:249-288 - create method
  • modules/tournament/src/main/TournamentApi.scala:56-71 - createTournament method
  • modules/tournament/src/main/TournamentForm.scala - Form validation

Build docs developers (and LLMs) love

Get started for freeTalk to us