Skip to main content

​
Introduction

The Lichess API provides programmatic access to Lichess’s features and data. It’s free, open, and used by thousands of applications worldwide.

REST API

Standard HTTP endpoints for games, users, tournaments, and more

Streaming API

Server-Sent Events for real-time game updates and activity

Bot API

Build chess bots that play on Lichess automatically

Authentication

OAuth2 for accessing user data and actions

​
Base URL

All API requests use the base URL: 
https://lichess.org

​
Response Formats

The API supports multiple response formats:
Standard JSON responses for most endpoints. Include Accept: application/json header or .json extension.
{
  "id": "q7ZvsdUF",
  "variant": "standard",
  "speed": "blitz",
  "status": "mate",
  "players": {
    "white": {
      "user": { "name": "player1", "id": "player1" },
      "rating": 1500
    }
  }
}
Newline-delimited JSON for streaming endpoints. Each line is a complete JSON object.
{"id":"abc123","moves":"e2e4"}
{"id":"def456","moves":"d2d4"}
{"id":"ghi789","moves":"c2c4"}
Standard chess notation format for game data.
[Event "Rated Blitz game"]
[Site "https://lichess.org/q7ZvsdUF"]
[Date "2024.03.06"]
[Round "-"]
[White "player1"]
[Black "player2"]
[Result "1-0"]

1. e4 e5 2. Nf3 Nc6 1-0

​
Authentication

Most endpoints work without authentication, but some features require an OAuth2 access token:
  • Creating games or challenges
  • Accessing private user data
  • Managing your account
  • Bot API endpoints
See the Authentication guide for details.

​
Rate Limiting

Rate limits protect the API from abuse:
  • Anonymous requests: More restrictive limits
  • Authenticated requests: Higher limits based on account standing
  • Streaming endpoints: Connection-based limits
See Rate Limits for specific values.

​
Versioning

The Lichess API does not use explicit versioning. Changes are backward-compatible when possible, with deprecation notices for breaking changes.
Subscribe to the Lichess changelog for API updates and announcements.

​
Best Practices

1

Use streaming endpoints

For real-time data, use streaming endpoints (NDJSON) instead of polling. This reduces load and provides instant updates.
2

Cache responses

Cache API responses when appropriate. Many endpoints include cache headers.
3

Handle errors gracefully

Implement exponential backoff for rate limit errors. Handle network failures with retries.
4

Include User-Agent

Set a descriptive User-Agent header with your app name and contact info:
User-Agent: MyChessApp/1.0 ([email protected])

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeMeaning
200Success
201Resource created
204Success with no content
400Bad request (invalid parameters)
401Unauthorized (missing or invalid token)
403Forbidden (insufficient permissions)
404Resource not found
429Too many requests (rate limited)
500Internal server error

​
Getting Help

Discord Community

Join the Lichess Discord for API support and discussions

GitHub Issues

Report bugs or request features on GitHub

​
Next Steps

Authentication

Set up OAuth2 authentication

Export Games

Download game data in PGN or JSON

Bot API

Create a chess bot

Build docs developers (and LLMs) love

Get started for freeTalk to us