Sign in

v3

latestOpenAPI 3.1.0AGPL-3.0-or-later2026-07-311871891.1 MB
Challenges

Create a challenge

Challenge someone to play. The targeted player can choose to accept or decline. If the challenge is accepted, you will be notified on the event stream that a new game has started. The game ID will be the same as the challenge ID. Challenges for realtime games (not correspondence) expire after 20s if not accepted. To prevent that, use the keepAliveStream flag described below.

post/api/challenge/{username}

Path parameters

usernamestring required
Example:LeelaChess

Response

The challenge was successfully created.

idstring required
urlstring uri required
status'created' | 'offline' | 'canceled' | 'declined' | 'accepted' required
ratedboolean required
speed'ultraBullet' | 'bullet' | 'blitz' | 'rapid' | 'classical' | 'correspondence' required
color'white' | 'black' | 'random' required
finalColor'white' | 'black'
direction'in' | 'out'
initialFenstring
rematchOfstring

Example response

{
  "id": "H9fIRZUk",
  "url": "https://lichess.org/H9fIRZUk",
  "status": "created",
  "challenger": {
    "id": "bot1",
    "name": "Bot1",
    "rating": 1500,
    "title": "BOT",
    "provisional": true,
    "online": true,
    "lag": 4
  },
  "destUser": {
    "id": "bobby",
    "name": "Bobby",
    "rating": 1635,
    "title": "GM",
    "provisional": true,
    "online": true,
    "lag": 4
  },
  "variant": {
    "key": "standard",
    "name": "Standard",
    "short": "Std"
  },
  "rated": true,
  "speed": "rapid",
  "timeControl": {
    "type": "clock",
    "limit": 600,
    "increment": 0,
    "show": "10+0"
  },
  "color": "random",
  "finalColor": "black",
  "perf": {
    "icon": "",
    "name": "Rapid"
  },
  "direction": "out"
}