LIlichess
Challenges

Open-ended challenge

Changed on

Create a challenge that any 2 players can join. Share the URL of the challenge. the first 2 players to click it will be paired for a game. The response body also contains whiteUrl and blackUrl. You can control which color each player gets by giving them these URLs, instead of the main challenge URL. Open challenges expire after 24h. If the challenge creation is authenticated with OAuth2, then you can use the challenge cancel endpoint to cancel it. To directly pair 2 known players, use this endpoint instead.

post/api/challenge/open

Request

  • Base URL
    https://lichess.org
  • URL
    https://lichess.org/api/challenge/open
  • Auth
    none required

Request body application/x-www-form-urlencoded

ratedboolean

Game is rated and impacts players ratings

clock.limitinteger

Clock initial time in seconds. If empty, a correspondence game is created.

clock.incrementinteger

Clock increment in seconds. If empty, a correspondence game is created.

days1 | 2 | 3 | 5 | 7 | 10 | 14

Days per turn. For correspondence challenges.

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

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.

namestring

Optional name for the challenge, that players will see on the challenge page.

rules'noRematch' | 'noGiveTime' | 'noClaimWin' | 'noEarlyDraw' | 'noAbort'

Extra game rules separated by commas. Example: noRematch,noGiveTime The noAbort rule is available for Lichess admins only

usersstring

Optional pair of usernames, separated by a comma. If set, only these users will be allowed to join the game. The first username gets the white pieces. Example: Username1,Username2

expiresAtinteger

Timestamp in milliseconds to expire the challenge. Defaults to 24h after creation. Can't be more than 2 weeks after creation.

Example request

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

Response

The challenge was successfully created.

idstring required
urlstring uri required
status'created' | 'offline' | 'canceled' | 'declined' | 'accepted' required
challengerunknown required
destUserunknown required
ratedboolean required
speed'ultraBullet' | 'bullet' | 'blitz' | 'rapid' | 'classical' | 'correspondence' required
color'white' | 'black' | 'random' required
finalColor'white' | 'black'
initialFenstring
urlWhitestring uri required
urlBlackstring uri required

Changes

  • 9b0422af5084Revision changes
    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status