Chess puzzles,
ready for your app.

Quick start

Base URL: https://oversky-chess.pages.dev. All endpoints accept GET and CORS preflight OPTIONS. No account or credentials are needed.

curl 'https://oversky-chess.pages.dev/api/v1/puzzle/random?theme=forks&difficulty=developing'

Without parameters, selection is uniform across all valid puzzles. Repeats are possible: the API does not track users or past requests. Each response is a single puzzle, never an array.

Repeat a specific puzzle

This returns the same six-field puzzle format. IDs are case-sensitive. This endpoint accepts no query parameters.

Lightweight health check

Returns status, API version, valid puzzles count and data release. This checks that the handler is running; it does not fetch or scan the database.

Choose the challenge

All random-endpoint parameters are optional. Values are case-sensitive. Empty values, repeated parameters and unknown parameter names return 400.

Custom rating range

minRating and maxRating accept integers from 600 to 2600, including both endpoints. If only one bound is given, the other defaults to 600 or 2600. The minimum cannot exceed the maximum.

/api/v1/puzzle/random?theme=pins&minRating=1000&maxRating=1499

A custom range replaces difficulty. Combining it with starter, developing, challenging or advanced returns 400 CONFLICTING_FILTERS. An omitted difficulty or difficulty=all is allowed. An empty matching set returns 404 NO_PUZZLES; the API never silently changes your filters.

A position ready to solve

Real response from /api/v1/puzzle/1JWGa:

{
  "id": "1JWGa",
  "rating": 835,
  "theme": "checkmate",
  "fen": "r5k1/p1Q2ppp/2p1p3/8/3P4/5q2/Pr3PBP/2R1R1K1 b - - 1 24",
  "lastMove": "f1g2",
  "solution": [
    "f3f2",
    "g1h1",
    "f2g2"
  ]
}

Read whose turn it is from the FEN. UCI uses coordinate notation such as e2e4, castling such as e1g1, and a promotion suffix such as a7a8q. En passant is represented by its ordinary from/to squares. Solutions are not SAN. A client should play solution[1] as the opponent’s reply after accepting solution[0], and continue alternating.

For a specific requested theme, the response uses that theme. For an unrestricted request or a request by ID, a multi-theme puzzle gets the first matching theme in this order: checkmate → forks → sacrifices → pins. If none applies, the response theme is endless. The theme is a label, not a complete list of tactical motifs.

All source lines are checked for legality during release generation. The API verifies source-file hashes before using them. This validates legal sequences, not a new chess-engine proof of optimality. The complete solution is public; it is not a competitive anti-cheat service.

Try it live

This makes a real request to the API on this website. It works after the API release is deployed.

Choose your filters and send a request.

/api/v1/puzzle/random

The actual JSON response will appear here.

Predictable errors

{"error":{"code":"INVALID_DIFFICULTY","message":"Unknown difficulty value"}}

Handler errors return JSON and CORS headers. 503 responses include Retry-After. Use exponential backoff with jitter for temporary failures and avoid retry loops. Hosting-level outages, exhausted Cloudflare quotas or edge security blocks can return a platform response outside this JSON contract; clients must check the HTTP status and Content-Type.

Free access, shared capacity

The API runs on Cloudflare’s free tier. As checked on 15 October 2026, the account’s Workers/Pages Functions allowance is 100,000 requests per day (shared with other Workers), with a 10 ms CPU budget per request and 128 MB per isolate. Limits can change; this is best-effort service with no uptime guarantee. Static trainer pages are routed separately from the API.

There is no enforced per-user rate limit in this release. Local concurrency protection bounds memory during bursts; it is not a distributed rate limiter and does not stop quota exhaustion. Fetch on demand, keep the current puzzle in your app, and avoid polling or bulk downloads. Random responses use Cache-Control: no-store; each call performs a new selection.

Credit the source

Puzzle data comes from the Lichess open puzzle database under CC0 1.0. Oversky Chess provides the selection, trainer and API. We appreciate a visible “Puzzles served by Oversky Chess” link to oversky-chess.pages.dev, plus acknowledgement of Lichess as the original data source. Attribution is appreciated; it is not a restriction added to the CC0 data.

Share or open a puzzle at https://oversky-chess.pages.dev/puzzle/{id}. See sources and software licenses.

Cloudflare pricing · Platform limits