{"openapi":"3.1.0","info":{"title":"Chess Puzzles API","version":"1.0.0","description":"Serve chess tactics puzzles on demand: a random puzzle (optionally constrained by theme and rating), a single puzzle by id, full search and filtering by tactic theme and difficulty rating, and the complete list of available themes. Every puzzle includes the starting position as FEN, the full solution as UCI moves, the side to move, the difficulty rating, popularity and play count, theme and opening tags and a direct link to train it on Lichess. Built on a curated 20,000-puzzle sample of the open Lichess puzzle database (CC0) spanning 73 themes and ratings from roughly 400 to 3100. Every endpoint accepts input via the query string or the request body and returns lean JSON. Pure server-side data (no third-party upstream), so responses are instant and always available. Ideal for chess apps, training tools, \"puzzle of the day\" features and games.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/chesspuzzles-api","description":"oanor gateway"}],"tags":[{"name":"Chess"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/puzzle":{"get":{"operationId":"get_v1_puzzle","tags":["Chess"],"summary":"Single puzzle by id","description":"","parameters":[{"name":"id","in":"query","required":true,"description":"Puzzle id","schema":{"type":"string"},"example":"00008"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"00008","fen":"r6k/pp2r2p/4Rp1Q/3p4/8/1N1P2R1/PqP2bPP/7K b - - 0 24","url":"https://lichess.org/training/00008","moves":["f2g3","e6e7","b2b1","b3c1","b1c1","h6c1"],"rating":1810,"themes":["crushing","hangingPiece","long","middlegame"],"game_url":"https://lichess.org/787zsVup/black#48","nb_plays":9527,"popularity":95,"opening_tags":[],"solver_color":"white"},"meta":{"timestamp":"2026-05-30T22:48:32.996Z","request_id":"27969b81-abde-4da7-8d5a-44444478596a"},"status":"ok","message":"Puzzle retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/random":{"get":{"operationId":"get_v1_random","tags":["Chess"],"summary":"Random puzzle by theme/rating","description":"","parameters":[{"name":"theme","in":"query","required":false,"description":"Tactic theme","schema":{"type":"string"},"example":"mateIn2"},{"name":"min_rating","in":"query","required":false,"description":"Minimum rating","schema":{"type":"string"},"example":"1200"},{"name":"max_rating","in":"query","required":false,"description":"Maximum rating","schema":{"type":"string"},"example":"1800"},{"name":"size","in":"query","required":false,"description":"1..10 (default 1)","schema":{"type":"string"},"example":"1"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"id":"93O0S","fen":"4rrk1/pp4pp/2np2b1/5N2/3P1R2/2P5/PP3QKR/3q4 b - - 0 23","url":"https://lichess.org/training/93O0S","moves":["e8e2","f5e7","c6e7","f4f8"],"rating":1415,"themes":["discoveredAttack","kingsideAttack","mate","mateIn2","middlegame","short"],"game_url":"https://lichess.org/prwN5T0y/black#46","nb_plays":1860,"popularity":96,"opening_tags":[],"solver_color":"white"},"meta":{"timestamp":"2026-05-30T22:48:33.072Z","request_id":"dd5c1e82-6b6d-40f7-be23-59066d7bbe6c"},"status":"ok","message":"Random puzzle retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/search":{"get":{"operationId":"get_v1_search","tags":["Chess"],"summary":"Search & filter puzzles","description":"","parameters":[{"name":"theme","in":"query","required":false,"description":"Tactic theme","schema":{"type":"string"},"example":"fork"},{"name":"min_rating","in":"query","required":false,"description":"Minimum rating","schema":{"type":"string"},"example":"1000"},{"name":"max_rating","in":"query","required":false,"description":"Maximum rating","schema":{"type":"string"},"example":"2000"},{"name":"sort","in":"query","required":false,"description":"rating|popularity|plays","schema":{"type":"string"},"example":"popularity"},{"name":"limit","in":"query","required":false,"description":"1..100 (default 20)","schema":{"type":"string"},"example":"20"},{"name":"offset","in":"query","required":false,"description":"Offset","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"sort":"popularity","count":20,"limit":20,"total":1630,"offset":0,"filters":{"theme":"fork","max_rating":2000,"min_rating":1000},"results":[{"id":"01tr2","fen":"8/5p1k/3q2pp/1R6/pP6/P1Q3PP/5PK1/3r4 w - - 1 37","url":"https://lichess.org/training/01tr2","moves":["b5b7","d6d5","c3f3","d1g1","g2g1","d5f3"],"rating":1348,"themes":["crushing","deflection","endgame","fork","long"],"game_url":"https://lichess.org/S2AzvY4t#73","nb_plays":322,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"0APD2","fen":"8/6kp/3qp1p1/1pp5/3nQ3/P6P/1P3P2/4R1K1 w - - 5 35","url":"https://lichess.org/training/0APD2","moves":["e4e5","d6e5","e1e5","d4f3","g1f1","f3e5"],"rating":1112,"themes":["attraction","crushing","endgame","fork","long"],"game_url":"https://lichess.org/mJqU5nlL#69","nb_plays":1001,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"0AnXJ","fen":"r5rk/pp3pp1/2q2P2/4p1QN/2Pn3P/3P4/P7/3K1R2 b - - 2 30","url":"https://lichess.org/training/0AnXJ","moves":["d4f3","f6g7","h8h7","h5f6","c6f6","g5f6"],"rating":1457,"themes":["advancedPawn","crushing","fork","long","middlegame"],"game_url":"https://lichess.org/SVBn7vaL/black#60","nb_plays":280,"popularity":100,"opening_tags":[],"solver_color":"white"},{"id":"0BI9t","fen":"r2k3r/pp3Bpp/1bp1N2n/4pq2/Q3N1b1/8/PP3PPP/R1n2R1K b - - 3 17","url":"https://lichess.org/training/0BI9t","moves":["d8c8","e4d6","c8b8","d6f5"],"rating":1020,"themes":["advantage","fork","middlegame","short"],"game_url":"https://lichess.org/umZF2NbU/black#34","nb_plays":146,"popularity":100,"opening_tags":["Scotch_Game","Scotch_Game_Scotch_Gambit"],"solver_color":"white"},{"id":"0ELzp","fen":"8/1k6/p1p1p3/P1P1P2p/2Q3p1/3r2K1/3r3N/8 w - - 3 36","url":"https://lichess.org/training/0ELzp","moves":["g3f4","d3d4","c4d4","d2d4"],"rating":1382,"themes":["crushing","endgame","fork","short"],"game_url":"https://lichess.org/OCzPWggq#71","nb_plays":91,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"0PbuS","fen":"r1bqkb1r/1pp4p/p3pn2/3NQ1p1/3P4/6P1/PPP2PBP/R3K2R b KQkq - 0 15","url":"https://lichess.org/training/0PbuS","moves":["f8g7","d5c7","e8f7","c7a8"],"rating":1773,"themes":["advantage","fork","middlegame","short"],"game_url":"https://lichess.org/1wGYERWB/black#30","nb_plays":528,"popularity":100,"opening_tags":["Hungarian_Opening","Hungarian_Opening_Other_variations"],"solver_color":"white"},{"id":"0SCce","fen":"r2q2k1/p1p3pp/1pQ5/3p1pNr/3P1P2/P3P3/1PP5/2KR4 b - - 0 21","url":"https://lichess.org/training/0SCce","moves":["h7h6","c6e6","g8h8","g5f7","h8h7","f7d8"],"rating":1160,"themes":["crushing","endgame","fork","long"],"game_url":"https://lichess.org/x29emM6P/black#42","nb_plays":30,"popularity":100,"opening_tags":[],"solver_color":"white"},{"id":"0Zvwj","fen":"4Rr1k/6p1/3q3p/3B1p2/p1Pp4/P4KP1/1P5P/4R3 b - - 0 32","url":"https://lichess.org/training/0Zvwj","moves":["f8e8","e1e8","h8h7","d5g8","h7g6","e8e6","d6e6","g8e6"],"rating":1138,"themes":["crushing","endgame","fork","master","masterVsMaster","veryLong"],"game_url":"https://lichess.org/XxhRI1xP/black#64","nb_plays":166,"popularity":100,"opening_tags":[],"solver_color":"white"},{"id":"0awxq","fen":"8/1pr4p/3p1k2/4nP2/2P1PK2/2R2B2/7P/8 w - - 11 46","url":"https://lichess.org/training/0awxq","moves":["c3c1","e5d3","f4e3","d3c1"],"rating":1269,"themes":["crushing","endgame","fork","master","masterVsMaster","short"],"game_url":"https://lichess.org/OSNQTEjE#91","nb_plays":68,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"0h2Kp","fen":"8/5k2/3p1pp1/pKp1b3/P1P3PP/1P6/8/4R3 w - - 0 42","url":"https://lichess.org/training/0h2Kp","moves":["b5a5","e5c3","a5b6","c3e1","a4a5","e1a5"],"rating":1182,"themes":["crushing","endgame","fork","long"],"game_url":"https://lichess.org/F2OAqhgV#83","nb_plays":965,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"16aPO","fen":"1k6/p1p3pp/5p2/8/2R5/2N2PP1/PPnr3P/7K w - - 1 26","url":"https://lichess.org/training/16aPO","moves":["c3e4","d2d1","h1g2","c2e3","g2f2","e3c4"],"rating":1019,"themes":["crushing","endgame","fork","long","master"],"game_url":"https://lichess.org/24NM76aH#51","nb_plays":303,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"17T3n","fen":"6R1/pp5r/1kp3p1/2N2n2/3P1p2/2P2P1P/PP4K1/8 w - - 14 38","url":"https://lichess.org/training/17T3n","moves":["g8g6","f5h4","g2f2","h4g6"],"rating":1351,"themes":["advantage","endgame","fork","short"],"game_url":"https://lichess.org/B0Cz9Yd6#75","nb_plays":357,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"1Fclv","fen":"5bk1/pQ4p1/1p2p3/7p/3PN3/P3B2q/1P3P2/4K3 w - - 0 32","url":"https://lichess.org/training/1Fclv","moves":["d4d5","h3h1","e1e2","h1e4"],"rating":1495,"themes":["endgame","equality","fork","short"],"game_url":"https://lichess.org/5xLcWVAX#63","nb_plays":88,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"1Zuc0","fen":"2Q5/p4Npk/5n1p/3p4/8/3p1NP1/q4r1P/3R2K1 b - - 7 30","url":"https://lichess.org/training/1Zuc0","moves":["f2f3","c8h8","h7g6","f7e5","g6f5","e5f3"],"rating":1149,"themes":["advantage","endgame","fork","long"],"game_url":"https://lichess.org/sBefG8pY/black#60","nb_plays":279,"popularity":100,"opening_tags":[],"solver_color":"white"},{"id":"1woL3","fen":"1R3b2/5pkp/p3p1p1/2p5/P1B1P3/2n4P/5PPK/8 w - - 3 31","url":"https://lichess.org/training/1woL3","moves":["f2f3","f8d6","g2g3","d6b8"],"rating":1064,"themes":["crushing","endgame","fork","master","short"],"game_url":"https://lichess.org/Rf25OFFi#61","nb_plays":487,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"1zRft","fen":"r1b2k1r/pp1p2p1/1b1P1q1p/n5p1/8/2NQ1N2/PP3PPP/R1B1R1K1 w - - 0 16","url":"https://lichess.org/training/1zRft","moves":["f3e5","f6f2","g1h1","f2e1","d3f1","e1f1"],"rating":1013,"themes":["fork","long","mate","mateIn3","opening"],"game_url":"https://lichess.org/dkFKS0Hw#31","nb_plays":1232,"popularity":100,"opening_tags":["Scotch_Game","Scotch_Game_Haxo_Gambit"],"solver_color":"black"},{"id":"1znQa","fen":"r5k1/8/p2pPqp1/2pP1rp1/1p6/8/PPPK2Q1/R4BR1 w - - 3 24","url":"https://lichess.org/training/1znQa","moves":["f1d3","f5f2","d2e1","f2g2"],"rating":1136,"themes":["advantage","fork","middlegame","short"],"game_url":"https://lichess.org/ku5tTAhw#47","nb_plays":124,"popularity":100,"opening_tags":[],"solver_color":"black"},{"id":"2CM5n","fen":"8/8/4B3/4qP1N/1p3k2/7P/P4PK1/8 b - - 4 52","url":"https://lichess.org/training/2CM5n","moves":["f4g5","f2f4","e5f4","h5f4"],"rating":1316,"themes":["crushing","endgame","fork","short"],"game_url":"https://lichess.org/3sxmKtlj/black#104","nb_plays":350,"popularity":100,"opening_tags":[],"solver_color":"white"},{"id":"2QGPO","fen":"r1bqkbnr/ppp4p/2N3p1/3p3Q/2B1p3/2P5/PP3PPP/RNB1K2R b KQkq - 0 8","url":"https://lichess.org/training/2QGPO","moves":["b7c6","h5e5","d8e7","e5h8"],"rating":1148,"themes":["advantage","fork","opening","short"],"game_url":"https://lichess.org/uX24c8TT/black#16","nb_plays":946,"popularity":100,"opening_tags":["Ponziani_Opening","Ponziani_Opening_Ponziani_Countergambit"],"solver_color":"white"},{"id":"2Tfwp","fen":"r5k1/p6p/1p6/2pn1B2/P2Bp3/1r1bP3/5P1P/R1R3K1 b - - 0 27","url":"https://lichess.org/training/2Tfwp","moves":["c5d4","f5e6","g8h8","e6d5"],"rating":1238,"themes":["advantage","fork","master","middlegame","short"],"game_url":"https://lichess.org/Wegre93d/black#54","nb_plays":447,"popularity":100,"opening_tags":[],"solver_color":"white"}]},"meta":{"timestamp":"2026-05-30T22:48:33.148Z","request_id":"4eeb131f-26ad-40c6-baa7-62e0520201eb"},"status":"ok","message":"Search completed","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/themes":{"get":{"operationId":"get_v1_themes","tags":["Chess"],"summary":"All tactic themes with counts","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":73,"themes":[{"name":"advancedPawn","puzzles":1175},{"name":"advantage","puzzles":5848},{"name":"anastasiaMate","puzzles":19},{"name":"arabianMate","puzzles":22},{"name":"attackingF2F7","puzzles":152},{"name":"attraction","puzzles":706},{"name":"backRankMate","puzzles":722},{"name":"balestraMate","puzzles":1},{"name":"bishopEndgame","puzzles":265},{"name":"blindSwineMate","puzzles":22},{"name":"bodenMate","puzzles":10},{"name":"capturingDefender","puzzles":135},{"name":"castling","puzzles":6},{"name":"clearance","puzzles":267},{"name":"collinearMove","puzzles":29},{"name":"cornerMate","puzzles":39},{"name":"crushing","puzzles":7640},{"name":"defensiveMove","puzzles":1225},{"name":"deflection","puzzles":901},{"name":"discoveredAttack","puzzles":1079},{"name":"discoveredCheck","puzzles":349},{"name":"doubleBishopMate","puzzles":15},{"name":"doubleCheck","puzzles":84},{"name":"dovetailMate","puzzles":16},{"name":"enPassant","puzzles":32},{"name":"endgame","puzzles":9907},{"name":"epauletteMate","puzzles":75},{"name":"equality","puzzles":47},{"name":"exposedKing","puzzles":601},{"name":"fork","puzzles":2540},{"name":"hangingPiece","puzzles":737},{"name":"hookMate","puzzles":32},{"name":"interference","puzzles":77},{"name":"intermezzo","puzzles":223},{"name":"killBoxMate","puzzles":27},{"name":"kingsideAttack","puzzles":1769},{"name":"knightEndgame","puzzles":154},{"name":"long","puzzles":5199},{"name":"master","puzzles":2802},{"name":"masterVsMaster","puzzles":261},{"name":"mate","puzzles":6376},{"name":"mateIn1","puzzles":2906},{"name":"mateIn2","puzzles":2697},{"name":"mateIn3","puzzles":666},{"name":"mateIn4","puzzles":78},{"name":"mateIn5","puzzles":29},{"name":"middlegame","puzzles":9117},{"name":"morphysMate","puzzles":37},{"name":"oneMove","puzzles":2913},{"name":"opening","puzzles":976},{"name":"operaMate","puzzles":211},{"name":"pawnEndgame","puzzles":765},{"name":"pillsburysMate","puzzles":223},{"name":"pin","puzzles":1226},{"name":"promotion","puzzles":446},{"name":"queenEndgame","puzzles":246},{"name":"queenRookEndgame","puzzles":167},{"name":"queensideAttack","puzzles":304},{"name":"quietMove","puzzles":809},{"name":"rookEndgame","puzzles":1079},{"name":"sacrifice","puzzles":1505},{"name":"short","puzzles":10197},{"name":"skewer","puzzles":415},{"name":"smotheredMate","puzzles":74},{"name":"superGM","puzzles":14},{"name":"swallowstailMate","puzzles":31},{"name":"trappedPiece","puzzles":233},{"name":"triangleMate","puzzles":27},{"name":"underPromotion","puzzles":1},{"name":"veryLong","puzzles":1602},{"name":"vukovicMate","puzzles":7},{"name":"xRayAttack","puzzles":87},{"name":"zugzwang","puzzles":216}],"rating_range":{"max":3101,"min":399},"total_puzzles":20000},"meta":{"timestamp":"2026-05-30T22:48:33.219Z","request_id":"5c0584cc-1812-40b2-a03a-ebcba1fc0ffa"},"status":"ok","message":"Themes retrieved","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":18000,"rps_limit":3,"hard_limit":true},{"slug":"basic","name":"Basic","price_cents_month":350,"monthly_call_quota":220000,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1100,"monthly_call_quota":1800000,"rps_limit":25,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":3100,"monthly_call_quota":9000000,"rps_limit":60,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/chesspuzzles-api"}