API for uploading puzzles and studies

[mratanusarkar]

Just like Lichess has APIs for downloading puzzles, it would be helpful if we had an API for upload, so that:

• one can upload private puzzles or newly created puzzles.
• one can upload private studies or newly created studies.
• bulk upload all the PGNs containing the studies/puzzles.
• some mechanism to organize the uploads via API to arrange them in a logical order of chapters in the "study" or "puzzle group"

For example: In case of single uploads, we can pass a JSON in the body with the single upload "ids" or "lichess upload urls", puzzle names, chapter names, and the title of the study. The JSON structure would be used to group them into chapters and order the chapters into one study.
For bulk upload, we can have a similar implementation and pass the information on how to organize the data in a JSON.

Note: The upload file type would be in PGN or FEN

If something similar already exists or there is a workaround, please help me out with the same.

[mratanusarkar]

I tried exploring the problem using APIs available from Lichess like https://lichess.org/api/import
but it only works for single-game uploads.

On exploring, I found that Lichess has a UI version of what I was looking for at https://lichess.org/study
It would be nice if we have an API version of the same, and it would be a great addition to the Lichess APIs.
We can have a new API as https://lichess.org/api/study

Please refer to the UI version below,
and taking all the input box data as input parameters of the API body, and creating a new API would resolve this issue.
For the second screen data, we can accept input as PGN, FEN, or links (from API response of /api/import or any valid link)

[mratanusarkar]

update: I had a workaround for this issue.

I went ahead and understood how PGN files work and how we can use multiple FEN in one game PGN to create positions of interest, and also store all metadata, annotations, markers, game info, and almost everything you can think of chess related, you can embed those data into a PGN, if you follow the format and the structure.

and if done correctly, you can manually generate study PGN files.

for the upload problem, how I tackled it was, just using the https://lichess.org/api/import API endpoint.
and storing the upload URL from the response:

uploaded_url_list = []

# your upload loop
uploaded_url_list.append(response.json()['url'])

and those would be links to your study uploads.

but still, there is a scope for a dedicated Lichess API for studies (eg: https://lichess.org/api/study),
where instead of crafting the PGN manually, the API could take in data as input from the request body, and generate a nice study with everything in one place, or as chapters.
(currently which is doable from the GUI: https://lichess.org/study as discussed above)

[ornicar]

What's your use case? Why do you need it, what are you building, and how will people use it?

[mratanusarkar]

@ornicar below are some rough answers to your question:

What's your use case?

My use case consists of various algorithms and automation scripts that pick up some important positions from given sets of games (offline or online games), and based on some clustering logic, group the findings (findings from my algorithm or automation scripts) into logical groups and categories which can be converted into studies (almost like a book of study with chapters and games!), that can help in chess preparations.

Why do you need it, What are you building?

I can't reveal much as this project is in collab with some GM and falls under NDA.
but I can share a little info such as:

• I went ahead and understood FEN and the file structure of PGN files
• with my current understanding of PGN, I can manually create PGNs, and convert the "findings" from my algo/script into a PGN that is auto-generated.
• If Lichess provides an API to create a study, It would be helpful to integrate Lichess study API with my automation and create studies from an automation script.
• The auto-generated study PGN already works well with ChessBase, but having Lichess integration will help to share things around via "Lichess study URLs".

How will people use it?

The Lichess GUI for Study is already quite sufficient and capable of handling a wide range of "study creation" scenarios. But having the same capability via an API would be powerful and help in various automation and upload scenarios (like one(s) in my use-case)