Import PGN to Study

{
  "error": "Invalid PGN format"
}

{
  "error": "Missing or invalid API token"
}

{
  "error": "You are not a contributor to this study"
}

{
  "error": "Study not found"
}

{
  "error": "Rate limit exceeded. Please slow down."
}

{
  "error": "Invalid PGN format"
}

{
  "error": "Missing or invalid API token"
}

{
  "error": "You are not a contributor to this study"
}

{
  "error": "Study not found"
}

{
  "error": "Rate limit exceeded. Please slow down."
}

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

string

required

The study ID (8 characters)

Request Body

Send as application/x-www-form-urlencoded:

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

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

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

string

default:"standard"

Chess variant. One of:

standard
chess960
crazyhouse
antichess
atomic
horde
kingOfTheHill
racingKings
threeCheck

string

default:"normal"

Chapter mode. One of:

normal - Standard analysis
practice - Practice mode (repeatable training)
gamebook - Interactive lesson format
conceal - Conceal future moves

boolean

default:"false"

If true, the first imported chapter becomes the new default chapter when opening the study.

boolean

default:"true"

If true, moves the study participants to the new chapter(s).

Response

Returns information about the imported chapters.

array

Array of imported chapter previews

Show properties

string

The chapter ID

string

The chapter name

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

{
  "error": "Missing or invalid API token"
}

{
  "error": "You are not a contributor to this study"
}

{
  "error": "Study not found"
}

{
  "error": "Rate limit exceeded. Please slow down."
}

Getting Started

Games

Users

Tournaments

Studies

Puzzles

Broadcasts

TV & Streaming

Bot API

Import PGN to Study

Import PGN chapters

Path Parameters

Request Body

Response

Example

Importing multiple games

Error responses

​Import PGN chapters

​Path Parameters

​Request Body

​Response

​Example

​Importing multiple games

​Error responses

Import PGN chapters

Path Parameters

Request Body

Response

Example

Importing multiple games

Error responses