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

string

required

The study ID (8 characters)

Query Parameters

boolean

default:"true"

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

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. }

boolean

default:"true"

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

boolean

default:"false"

Add a Source PGN tag with the study chapter URL.

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.

string

application/x-chess-pgn

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

string

required

The study ID (8 characters)

string

required

The chapter ID (8 characters)

Query Parameters

boolean

default:"true"

Include clock comments in the PGN moves, when available.

boolean

default:"true"

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

boolean

default:"true"

Include non-mainline moves, when available.

boolean

default:"false"

Add a Source PGN tag with the study chapter URL.

boolean

default:"false"

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

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.

string

application/x-chess-pgn

string

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

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

string

required

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

Query Parameters

boolean

default:"true"

Include clock comments in the PGN moves, when available.

boolean

default:"true"

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

boolean

default:"true"

Include non-mainline moves, when available.

boolean

default:"false"

Add a Source PGN tag with the study chapter URL.

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.

string

application/x-chess-pgn

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

string

required

The username

Response

Returns an nd-json stream of study metadata objects.

string

The study ID

string

The study name

integer

Unix timestamp in milliseconds

integer

Unix timestamp in milliseconds

object

Study owner information

Show properties

string

The owner’s user ID

string

The owner’s username

array

List of study members (contributors)

integer

Number of chapters in the study

integer

Number of likes the study has received

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

​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

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