Export Studies

Export a single study

This endpoint is rate limited.

GET https://lichess.org/api/study/{studyId}.pgn

Exports all chapters of a study in PGN format.

Path Parameters

studyId

string

required

The study ID (8 characters)

Query Parameters

clocks

boolean

default:"true"

Include clock comments in the PGN moves, when available.Example: 2. exd5 { [%clk 1:01:27] } e5 { [%clk 1:01:28] }

comments

boolean

default:"true"

Include analysis and annotator comments in the PGN moves, when available.Example: 12. Bxf6 { [%cal Gf6g7] } gxf6 { White is slightly better here. }

variations

boolean

default:"true"

Include non-mainline moves, when available.Example: 4. d4 Bb4+ (4... Nc6 5. Nf3 e6 6. Bd3) 5. Nd2

source

boolean

default:"false"

Add a Source PGN tag with the study chapter URL.

orientation

boolean

default:"false"

Add a Orientation PGN tag with the chapter’s configured orientation.

Response

Returns a PGN file with all chapters of the study. Each chapter is represented as a separate game in the PGN.

Content-Type

string

application/x-chess-pgn

Content-Disposition

string

attachment; filename="{study-name}.pgn"

Example

curl -X GET "https://lichess.org/api/study/XtFCFYlM.pgn?comments=true&variations=true"

[Event "Sicilian Najdorf: Introduction"]
[Site "https://lichess.org/study/XtFCFYlM/GCUTf2jk"]
[Result "*"]
[Variant "Standard"]
[ECO "B90"]
[Opening "Sicilian Defense: Najdorf Variation, English Attack"]
[Annotator "https://lichess.org/@/veloce"]
[UTCDate "2017.07.26"]
[UTCTime "17:48:11"]

1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 a6 { This is the Najdorf Variation. } 6. Be3 *


[Event "Sicilian Najdorf: Main Line"]
[Site "https://lichess.org/study/XtFCFYlM/kYKDRmpd"]
[Result "*"]
[Variant "Standard"]
[ECO "B90"]
[Opening "Sicilian Defense: Najdorf Variation"]
[Annotator "https://lichess.org/@/veloce"]
[UTCDate "2017.07.26"]
[UTCTime "17:50:03"]

1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 a6 *

Export a single chapter

GET https://lichess.org/api/study/{studyId}/{chapterId}.pgn

Exports a single chapter of a study in PGN format.

Path Parameters

studyId

string

required

The study ID (8 characters)

chapterId

string

required

The chapter ID (8 characters)

Query Parameters

clocks

boolean

default:"true"

Include clock comments in the PGN moves, when available.

comments

boolean

default:"true"

Include analysis and annotator comments in the PGN moves, when available.

variations

boolean

default:"true"

Include non-mainline moves, when available.

source

boolean

default:"false"

Add a Source PGN tag with the study chapter URL.

orientation

boolean

default:"false"

Add a Orientation PGN tag with the chapter’s configured orientation.

analysisHeader

boolean

default:"false"

If the chapter has a computer analysis, include it in a custom X-Lichess-Analysis HTTP header.The analysis is returned as a JSON object containing evaluation and best moves.

Response

Returns a PGN file with the requested chapter.

Content-Type

string

application/x-chess-pgn

Content-Disposition

string

attachment; filename="{study-name}_{chapter-name}.pgn"

X-Lichess-Analysis

string

JSON analysis data (only if analysisHeader=true and analysis is available)

Example

curl -X GET "https://lichess.org/api/study/XtFCFYlM/GCUTf2jk.pgn"

[Event "Sicilian Najdorf: Introduction"]
[Site "https://lichess.org/study/XtFCFYlM/GCUTf2jk"]
[Result "*"]
[Variant "Standard"]
[ECO "B90"]
[Opening "Sicilian Defense: Najdorf Variation, English Attack"]
[Annotator "https://lichess.org/@/veloce"]
[UTCDate "2017.07.26"]
[UTCTime "17:48:11"]

1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 a6 { This is the Najdorf Variation. } 6. Be3 *

Export all studies of a user

GET https://lichess.org/api/study/by/{username}/export.pgn

Download all chapters of all studies owned by a user, in PGN format.

If authenticated as the user, private and unlisted studies are included. Otherwise, only public studies are exported.

Path Parameters

username

string

required

The username. Use me to export studies of the authenticated user.

Query Parameters

clocks

boolean

default:"true"

Include clock comments in the PGN moves, when available.

comments

boolean

default:"true"

Include analysis and annotator comments in the PGN moves, when available.

variations

boolean

default:"true"

Include non-mainline moves, when available.

source

boolean

default:"false"

Add a Source PGN tag with the study chapter URL.

orientation

boolean

default:"false"

Add a Orientation PGN tag with the chapter’s configured orientation.

Response

Returns a streaming PGN file containing all chapters from all studies. This may be a very large file depending on how many studies the user has created.

Content-Type

string

application/x-chess-pgn

Content-Disposition

string

attachment; filename="{username}-all-studies.pgn" or {username}-public-studies.pgn

Example

curl -X GET "https://lichess.org/api/study/by/veloce/export.pgn" \
  -H "Authorization: Bearer {token}"

List studies of a user

GET https://lichess.org/api/study/by/{username}

Get metadata about all studies owned by a user.

If authenticated as the user, private and unlisted studies are included. Otherwise, only public studies are returned.

Path Parameters

username

string

required

The username

Response

Returns an nd-json stream of study metadata objects.

string

The study ID

name

string

The study name

createdAt

integer

Unix timestamp in milliseconds

updatedAt

integer

Unix timestamp in milliseconds

owner

object

Study owner information

Show properties

string

The owner’s user ID

name

string

The owner’s username

members

array

List of study members (contributors)

chapters

integer

Number of chapters in the study

likes

integer

Number of likes the study has received

visibility

string

One of: public, unlisted, or private

Example

curl -X GET "https://lichess.org/api/study/by/veloce"

{"id":"XtFCFYlM","name":"Sicilian Najdorf","createdAt":1501089491064,"updatedAt":1501090203373,"owner":{"id":"veloce","name":"veloce"},"members":[{"user":{"id":"veloce","name":"veloce"},"role":"w"}],"chapters":2,"likes":15,"visibility":"public"}
{"id":"9ogFv8Ac","name":"French Defense","createdAt":1497729143527,"updatedAt":1501759179630,"owner":{"id":"veloce","name":"veloce"},"members":[{"user":{"id":"veloce","name":"veloce"},"role":"w"}],"chapters":12,"likes":42,"visibility":"public"}

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

Export a single study

Path Parameters

Query Parameters

Response

Example

Export a single chapter

Path Parameters

Query Parameters

Response

Example

Export all studies of a user

Path Parameters

Query Parameters

Response

Example

List studies of a user

Path Parameters

Response

Example

Build docs developers (and LLMs) love

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

​Export a single study

​Path Parameters

​Query Parameters

​Response

​Example

​Export a single chapter

​Path Parameters

​Query Parameters

​Response

​Example

​Export all studies of a user

​Path Parameters

​Query Parameters

​Response

​Example

​List studies of a user

​Path Parameters

​Response

​Example

Build docs developers (and LLMs) love

Export a single study

Path Parameters

Query Parameters

Response

Example

Export a single chapter

Path Parameters

Query Parameters

Response

Example

Export all studies of a user

Path Parameters

Query Parameters

Response

Example

List studies of a user

Path Parameters

Response

Example