Skip to main content

​
Import PGN chapters

Requires OAuth scope: study:write
POST https://lichess.org/api/study/{studyId}/import-pgn
Import PGN content into a study. Creates one or more chapters from the provided PGN.
  • You must be a contributor to the study.
  • Multiple games in the PGN will create multiple chapters.
  • Maximum number of chapters per study is enforced.
  • This endpoint is rate limited based on the number of chapters being imported.

​
Path Parameters

​
studyId
string
required
The study ID (8 characters)

​
Request Body

Send as application/x-www-form-urlencoded:
​
name
string
Name for the chapter. If importing multiple games, only the first chapter will use this name. Other chapters will use names from the PGN Event tag or a default name.Maximum length: 100 characters
​
pgn
string
required
The PGN content to import. Can contain one or more games separated by blank lines.Supports:
  • Standard PGN format
  • Multiple games (each becomes a separate chapter)
  • Comments and variations
  • PGN tags (Event, Site, Date, etc.)
  • Clock annotations
  • Evaluation annotations
​
orientation
string
default:"auto"
Chapter orientation. One of:
  • auto - Automatic based on the game
  • white - Always show from white’s perspective
  • black - Always show from black’s perspective
​
variant
string
default:"standard"
Chess variant. One of:
  • standard
  • chess960
  • crazyhouse
  • antichess
  • atomic
  • horde
  • kingOfTheHill
  • racingKings
  • threeCheck
​
mode
string
default:"normal"
Chapter mode. One of:
  • normal - Standard analysis
  • practice - Practice mode (repeatable training)
  • gamebook - Interactive lesson format
  • conceal - Conceal future moves
​
initial
boolean
default:"false"
If true, the first imported chapter becomes the new default chapter when opening the study.
​
sticky
boolean
default:"true"
If true, moves the study participants to the new chapter(s).

​
Response

Returns information about the imported chapters.
​
chapters
array
Array of imported chapter previews
​
error
string
Error message if the import partially failed

​
Example

curl -X POST "https://lichess.org/api/study/XtFCFYlM/import-pgn" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=My New Chapter" \
  -d "pgn=[Event \"Casual Game\"]
[Site \"lichess.org\"]
[Result \"*\"]

1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 *" \
  -d "orientation=white" \
  -d "mode=normal" \
  -d "sticky=true"

{
  "chapters": [
    {
      "id": "kYKDRmpd",
      "name": "My New Chapter"
    }
  ]
}

​
Importing multiple games

You can import multiple games at once by separating them with blank lines in the PGN: 
curl -X POST "https://lichess.org/api/study/XtFCFYlM/import-pgn" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "pgn=[Event \"Game 1\"]
[Site \"lichess.org\"]
[Result \"1-0\"]

1. e4 e5 2. Nf3 1-0

[Event \"Game 2\"]
[Site \"lichess.org\"]
[Result \"0-1\"]

1. d4 d5 2. c4 0-1" \
  -d "sticky=false"

{
  "chapters": [
    {
      "id": "abc12345",
      "name": "Game 1"
    },
    {
      "id": "def67890",
      "name": "Game 2"
    }
  ]
}

​
Error responses

{
  "error": "Invalid PGN format"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us