Accounts & collections

Native-app username/password sign-in. If the account has authenticator 2FA enabled, retry with two_factor_code after receiving two_factor_required.

Example

curl -X POST "https://classicchess.com/api/v1/account/mobile/login/" -H "Content-Type: application/json" -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD","device_name":"Android phone"}'

Revoke the current mobile session credential.

List active Android and Desktop sessions owned by the authenticated account. The response contains device metadata and a current-session marker, never bearer material.

Revoke one active device session owned by the authenticated account.

Revoke every device session, including the credential making the request.

Native-app account settings for board theme, piece set, and Stockfish preferences. Requires a mobile session credential.

Authenticated account summary. Requires account:read.

List collections with library:read, or create one with library:write.

Create example

curl -X POST "https://classicchess.com/api/v1/account/collections/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN" -H "Content-Type: application/json" -d '{"name":"Tal 1960-1965"}'

List games inside one owned collection with library:read; rename or delete it with library:write. Other users' collections return 404.

Remove one game from an owned collection. Requires library:write; other users' collections return 404.

Create or reuse a collection and import public archive player games. Requires library:write.

Example

curl -X POST "https://classicchess.com/api/v1/account/collections/import/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN" -H "Content-Type: application/json" -d '{"source":"public_player_games","name":"Tal 1960-1965","archive_player":"mikhail-tal","since":1960,"until":1965}'

Response

{
  "ok": true,
  "collection": { "id": 123, "name": "Tal 1960-1965", "sort": "added", "game_count": 42 },
  "created_collection": true,
  "matched": 42,
  "added": 42,
  "already_present": 0,
  "skipped": 0
}

List/search imported games with library:read, or import one pasted PGN / supported public game URL with library:write.

Owned imported-game detail with PGN and board-ready mainline, with library:read. With library:write, PATCH {"visibility": "private"} or "public" changes who can see it, and DELETE permanently removes it, including from every collection and starred list. Other users' imports return 404. Making a game private hides it from other accounts' collections and stars.

Animated GIF of one of your own imports, public or private, with library:read. Accepts ?orientation=black and format=mp4 for an MP4 video. Shares the site-wide per-account GIF limit; a 429 carries Retry-After.

Add one game to an owned collection with library:write. Send {"game": "GAME_SLUG"}: any public archive game, a public imported game, or your own import. Returns 201 with the new item, or 200 with changed false if it was already there. Other accounts' private imports and collections return 404.

Example

curl -X POST "https://classicchess.com/api/v1/account/collections/123/items/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN" -H "Content-Type: application/json" -d '{"game":"tal-vs-larsen-1965"}'

GET /api/v1/account/starred/players/ lists your starred players, newest first, with library:read. PUT stars and DELETE unstars one public archive player with library:write; both are idempotent and report changed. The older toggle at /api/v1/account/players/{player_slug}/bookmark/ remains supported.

Example

curl -X PUT "https://classicchess.com/api/v1/account/starred/players/mikhail-tal/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

GET /api/v1/account/starred/games/ lists your starred games, newest first, with library:read. PUT stars any game you can open and DELETE unstars it, with library:write. A game another account imported and later made private disappears from your list but can still be unstarred.

Example

curl -X DELETE "https://classicchess.com/api/v1/account/starred/games/tal-vs-larsen-1965/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

Your notification inbox, newest first, with notifications:read. Paged with page and page_size (at most 100). unread_count matches the website bell.

Example

curl "https://classicchess.com/api/v1/account/notifications/?page_size=20" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

Mark one notification read with notifications:write. Safe to retry; returns the new unread_count.

Mark every notification read with notifications:write. Returns how many changed.

Dismiss one notification from the inbox with notifications:write. Notifications outside your inbox return 404.

Empty the inbox: dismiss every notification in it with notifications:write, as the website's trash beside the notification settings does. Safe to retry; returns how many were dismissed as dismissed and the new unread_count.

Each topic with its on-site choice and default, plus the sound setting, with notifications:read. PATCH with notifications:write and a body such as {"topics": {"TOPIC_KEY": false}, "sound_enabled": true}; only the named settings change. Unknown topics or non-boolean values return 400 and change nothing.

Notebooks you own or were invited to, most recently updated first, with notebooks:read. Each summary says whether you can export it.

Example

curl "https://classicchess.com/api/v1/account/notebooks/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

Folders and chapters of any Notebook you can open, with notebooks:read. A chapter urls.api_pgn is empty when you cannot export the Notebook.

Download the whole Notebook as a .ccnb file with notebooks:read. Members may always export; other accounts only when the owner allowed public exports. Members may POST {"password": "..."} for a password-protected file; the password is not stored.

Example

curl --output notebook.ccnb "https://classicchess.com/api/v1/account/notebooks/NOTEBOOK_UUID/file/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

Download one chapter as PGN with notebooks:read, under the same export rule.

The bots, the time controls a new game may use, and your newest games, with gym:read.

Example

curl "https://classicchess.com/api/v1/account/gym/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

Your games, newest first, paged with page and page_size (up to 100).

Start a game with gym:play. The body may give color (white, black or random) and time: unlimited, a preset such as 3+0, or custom with minutes and increment. When you play Black, bot_to_move is true; ask for the bot's move next.

Example

curl -X POST "https://classicchess.com/api/v1/account/gym/bots/morphy/games/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN" -H "Content-Type: application/json" -d '{"color":"white","time":"5+0"}'

One game with its clock settled, with gym:read; DELETE removes it with gym:play. /pgn/ downloads the game as PGN.

Play your move as UCI with the ply you have seen, for example {"move": "e2e4", "ply": 0}. A stale ply returns 409 and plays nothing, so a repeated request is safe. Then POST bot-move/ with the new ply for the bot's reply.

Example

curl -X POST "https://classicchess.com/api/v1/account/gym/games/GAME_ID/move/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN" -H "Content-Type: application/json" -d '{"move":"e2e4","ply":0}'

resign/, takeback/, clock/ (call when a clock you show reaches zero; the server decides) and abort/ (before your first move; the game is deleted), each with gym:play.

Your figures, with puzzles:read: puzzles solved on the first try, puzzles missed, what is left in your rotation, and the total.

Example

curl "https://classicchess.com/api/v1/account/puzzles/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

A random puzzle from your rotation. Pass after with the puzzle you just played to get another one. The puzzle has the game so far (start_fen and lead), its position (fen) and solution.moves: the accepted moves at each point are the entries whose after equals the moves played so far. When every puzzle is solved the answer is 404 rotation_empty.

Example

curl "https://classicchess.com/api/v1/account/puzzles/next/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN"

One puzzle, for example from your history. game links the source game's API address and page at the puzzle position when the game is available.

Save how one play went, with puzzles:write, for example {"result": "solved"}. A first-try solve stands until you reset your puzzles, so the saved result in the answer can differ from the one you sent.

Example

curl -X POST "https://classicchess.com/api/v1/account/puzzles/PUZZLE_ID/result/" -H "Authorization: Bearer $CLASSICCHESS_API_TOKEN" -H "Content-Type: application/json" -d '{"result":"solved"}'

The puzzles you have played and how you did, most recent first, paged with page and page_size (up to 100).

Reset your puzzles, with puzzles:write: every puzzle goes back into your rotation. Your history stays.