Join Arena Tournament

Overview

Join an arena tournament. Players can join at any time during the tournament, though it’s recommended to join before it starts for maximum participation.

Requires authentication with OAuth token that has tournament:write, bot:play, or web:mobile scope.

Endpoint

curl -X POST https://lichess.org/api/tournament/{tournamentId}/join \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"password": "secret", "team": "team-id"}'

Authentication

Requires OAuth token with one of:

tournament:write scope
bot:play scope (for bot accounts)
web:mobile scope (for mobile clients)

Authorization: Bearer lip_xxxxxxxxxxxx

Path Parameters

string

required

8-character tournament ID

Request Body

string

Password for private tournaments. Required if the tournament has password protection

string

Team ID to join with (required for team battle tournaments). You must be a member of the team

boolean

If true, request immediate pairing. Only works if tournament has already started

Response

Returns a JSON object indicating success or failure:

boolean

true if successfully joined, false if failed

boolean

true if successfully joined (deprecated, use ok instead)

string

Error message if join failed

Example Response

{
  "ok": true
}

{
  "ok": true
}

{
  "joined": false,
  "error": "Wrong entry code"
}

{
  "joined": false,
  "error": "Missing team"
}

Join Result Codes

Possible error messages:

Incorrect password provided for private tournament

You have a temporary ban from joining tournaments

You don’t meet the tournament entry conditions (rating, account age, etc.)

Team battle tournament requires a team selection, or you’re not a member of the specified team

Your account has an arena ban

Your account has a prize ban and the tournament description mentions prizes

Rate limit exceeded for tournament joins

Tournament ID is invalid or tournament was deleted

Entry Conditions

Tournaments may have various entry conditions:

Rating Requirements

Minimum rating in the tournament’s performance type
Maximum rating in the tournament’s performance type

Account Requirements

Minimum number of rated games in the performance type
Minimum account age

Team Requirements

Team membership for team-restricted tournaments
Team selection for team battle tournaments

Other Restrictions

Password protection
Allow-list (only specific users can join)
No arena-banned or prize-banned accounts

User-Specific Access Codes

Tournament passwords can be user-specific. If a tournament uses HMAC-based access codes, each user has a unique password calculated as:

HMAC-SHA256(tournament_password, user_id)

This allows tournament organizers to distribute individual codes to participants.

Rate Limits

Joining tournaments is rate-limited:

8 joins per hour for first-time joins
30 joins per day for first-time joins
Lower cost for:
- Team leaders joining their team’s tournaments
- Re-joining tournaments already joined
- Official Lichess tournaments

Timing Considerations

Joining Before Start

You can join any time before the tournament starts
You’ll be paired in the first round when the tournament starts

Joining After Start

You can still join after the tournament starts
You’ll be paired as soon as possible
Your score starts at 0 regardless of current round
Use pairMeAsap: true to request immediate pairing

Joining Late

You can join up until pairings are closed (typically last 30-120 seconds of tournament)
Late joiners have fewer opportunities to play games

Team Battle Specifics

For team battle tournaments:

You must be a member of one of the participating teams
You must specify which team to join with via the team parameter
Once the tournament starts, you cannot change teams
Your score contributes to your team’s total score

Withdrawing

To withdraw from a tournament, use the Withdraw endpoint:

POST /api/tournament/{tournamentId}/withdraw

Example Usage

Join a Public Tournament

curl -X POST https://lichess.org/api/tournament/QITRjufu/join \
  -H "Authorization: Bearer lip_xxxxxxxxxxxx"

Join a Private Tournament

curl -X POST https://lichess.org/api/tournament/QITRjufu/join \
  -H "Authorization: Bearer lip_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"password": "my-secret-password"}'

Join a Team Battle

curl -X POST https://lichess.org/api/tournament/QITRjufu/join \
  -H "Authorization: Bearer lip_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"team": "my-team-id"}'

Join and Request Immediate Pairing

curl -X POST https://lichess.org/api/tournament/QITRjufu/join \
  -H "Authorization: Bearer lip_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"pairMeAsap": true}'

List Tournaments - Get all current tournaments
Get Tournament Details - Get full tournament information
Withdraw from Tournament - Leave a tournament
Create Tournament - Create a new tournament

Source Code Reference

Implementation can be found in:

app/controllers/Tournament.scala:176-194 - join and apiJoin methods
modules/tournament/src/main/TournamentApi.scala:285-344 - join method
modules/tournament/src/main/TournamentForm.scala:139-154 - Join form validation

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

Join Arena Tournament

Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Response

Join Result Codes

Entry Conditions

Rating Requirements

Account Requirements

Team Requirements

Other Restrictions

User-Specific Access Codes

Rate Limits

Timing Considerations

Joining Before Start

Joining After Start

Joining Late

Team Battle Specifics

Withdrawing

Example Usage

Join a Public Tournament

Join a Private Tournament

Join a Team Battle

Join and Request Immediate Pairing

Source Code Reference

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Example Response

​Join Result Codes

​Entry Conditions

​Rating Requirements

​Account Requirements

​Team Requirements

​Other Restrictions

​User-Specific Access Codes

​Rate Limits

​Timing Considerations

​Joining Before Start

​Joining After Start

​Joining Late

​Team Battle Specifics

​Withdrawing

​Example Usage

​Join a Public Tournament

​Join a Private Tournament

​Join a Team Battle

​Join and Request Immediate Pairing

​Related Endpoints

​Source Code Reference

Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Response

Join Result Codes

Entry Conditions

Rating Requirements

Account Requirements

Team Requirements

Other Restrictions

User-Specific Access Codes

Rate Limits

Timing Considerations

Joining Before Start

Joining After Start

Joining Late

Team Battle Specifics

Withdrawing

Example Usage

Join a Public Tournament

Join a Private Tournament

Join a Team Battle

Join and Request Immediate Pairing

Related Endpoints

Source Code Reference