Board

Create a seek

Create a public seek, to start a game with a random player.

Real-time seek

Specify the time and increment clock values. The response is streamed but doesn't contain any information.

Keep the connection open to keep the seek active.

If the client closes the connection, the seek is canceled. This way, if the client terminates, the user won't be paired in a game they wouldn't play. When the seek is accepted, or expires, the server closes the connection.

Make sure to also have an Event stream open, to be notified when a game starts. We recommend opening the Event stream first, then the seek stream. This way, you won't miss the game event if the seek is accepted immediately.

Correspondence seek

Specify the days per turn value. The response is not streamed, it immediately completes with the seek ID. The seek remains active on the server until it is joined by someone.

post/api/board/seek

Request

  • Base URL
    https://lichess.org
  • URL
    https://lichess.org/api/board/seek
  • Auth
    OAuth 2
    Authorization code: https://lichess.org/oauth
    Token URL: https://lichess.org/api/token scopes: board:play

Request body application/x-www-form-urlencoded

OR

Example request

{
  "rated": true,
  "time": 15,
  "increment": 15
}

Response

The seek was successfully created.

idstring required

Changes

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