Skip to main content

​
Delete a chapter

Requires OAuth scope: study:write
DELETE https://lichess.org/api/study/{studyId}/{chapterId}
Delete a chapter from a study.
You must be the study owner or have study admin permissions.If you delete the only chapter in a study, a new empty chapter will be automatically created.

​
Path Parameters

​
studyId
string
required
The study ID (8 characters)
​
chapterId
string
required
The chapter ID to delete (8 characters)

​
Response

Returns HTTP 204 No Content on success.

​
Example

curl -X DELETE "https://lichess.org/api/study/XtFCFYlM/kYKDRmpd" \
  -H "Authorization: Bearer {token}"

​
Error responses

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

​
Update chapter PGN tags

Requires OAuth scope: study:write
POST https://lichess.org/api/study/{studyId}/{chapterId}/tags
Update the PGN tags (metadata) of a study chapter.
  • You must be a contributor to the study.
  • Existing tags not mentioned in the request are preserved.
  • To delete a tag, send it with an empty value.
  • Only standard PGN tags and some custom tags are allowed.

​
Path Parameters

​
studyId
string
required
The study ID (8 characters)
​
chapterId
string
required
The chapter ID (8 characters)

​
Request Body

Send as application/x-www-form-urlencoded:
​
pgn
string
required
PGN tags to update, in standard PGN tag format.Format: [TagName "Tag Value"]Multiple tags should be separated by newlines.

​
Supported PGN Tags

Standard tags:
  • Event - Event name
  • Site - Site/location
  • Date - Date in YYYY.MM.DD format
  • Round - Round number
  • White - White player name
  • Black - Black player name
  • Result - Game result (1-0, 0-1, 1/2-1/2, or *)
  • Annotator - Annotator name
  • ECO - Opening ECO code
  • Opening - Opening name
  • Variant - Chess variant
  • TimeControl - Time control
  • WhiteElo - White player rating
  • BlackElo - Black player rating
  • WhiteTitle - White player title (GM, IM, etc.)
  • BlackTitle - Black player title
  • FEN - Starting position (for non-standard starts)

​
Response

Returns HTTP 204 No Content on success.

​
Example

Update multiple tags: 
curl -X POST "https://lichess.org/api/study/XtFCFYlM/kYKDRmpd/tags" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'pgn=[Event "World Championship"]
[Site "London"]
[Date "2023.04.15"]
[White "Carlsen, Magnus"]
[Black "Nepomniachtchi, Ian"]
[WhiteElo "2853"]
[BlackElo "2795"]
[ECO "C42"]
[Opening "Russian Game"]'
Delete a tag by setting it to empty: 
curl -X POST "https://lichess.org/api/study/XtFCFYlM/kYKDRmpd/tags" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'pgn=[Annotator ""]'

​
Error responses

{
  "error": "Invalid PGN tag format"
}

​
Additional Information

​
Chapter IDs

Chapter IDs are 8-character alphanumeric strings that uniquely identify a chapter within Lichess. You can find chapter IDs in:
  • The URL when viewing a chapter: lichess.org/study/{studyId}/{chapterId}
  • The response from the Import PGN endpoint
  • The chapter list when viewing a study in the Lichess interface

​
Rate Limits

All chapter management endpoints are rate limited. The exact limits depend on:
  • Your account status (titled players and coaches have higher limits)
  • Your IP address
  • The specific operation being performed
If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

​
Permissions

Study Owner

Full access to all chapter operations including deletion and tag updates.

Contributors

Can update chapter tags and import PGN, but cannot delete chapters unless they are the study owner.

Study Admin

Special permission that grants owner-level access. Requires the study:admin permission.

Read-only

Can only view and export chapters. Cannot make any modifications.

Build docs developers (and LLMs) love

Get started for freeTalk to us