org.lichess.puzzle.getNextRanked

pds.dad

Documentation

Fetches the next ranked puzzle for the authenticated player. Each puzzle needs to be solved or failed before requesting another; if the player already holds an unresolved ranked puzzle, that same puzzle (with a freshly re-signed challenge) is returned so a client that lost its token can recover it.

main query

Fetches the next ranked puzzle for the authenticated player. Each puzzle needs to be solved or failed before requesting another; if the player already holds an unresolved ranked puzzle, that same puzzle (with a freshly re-signed challenge) is returned so a client that lost its token can recover it.

Output

Encodingapplication/json
challenge string Required

Opaque signed token (JWT/HMAC/ed25519) encoding puzzleId, player DID, rating+RD snapshot, puzzle rating, nonce, and expiry. Passed back verbatim to submitAttempt. Empty for casual if you choose not to issue one.

ranked boolean Required

Echoes whether this puzzle is scored.

Errors

OutstandingPuzzle The player already has an unresolved ranked puzzle. Submit or let it time out before requesting another. This is what blocks request-peek-reroll grinding.
NoPuzzleAvailable No puzzle matched the requested filters.
PlayerLimited The player is temporarily blocked from ranked play. The message includes the RFC 3339 timestamp when the limit lifts. Submitting an already-outstanding puzzle still works.
Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Base URL for XRPC calls (e.g., https://api.bsky.social)
View raw schema 
{
  "type": "query",
  "errors": [
    {
      "name": "OutstandingPuzzle",
      "description": "The player already has an unresolved ranked puzzle. Submit or let it time out before requesting another. This is what blocks request-peek-reroll grinding."
    },
    {
      "name": "NoPuzzleAvailable",
      "description": "No puzzle matched the requested filters."
    },
    {
      "name": "PlayerLimited",
      "description": "The player is temporarily blocked from ranked play. The message includes the RFC 3339 timestamp when the limit lifts. Submitting an already-outstanding puzzle still works."
    }
  ],
  "output": {
    "schema": {
      "type": "object",
      "required": [
        "puzzle",
        "ranked",
        "challenge"
      ],
      "properties": {
        "puzzle": {
          "ref": "org.lichess.puzzle.defs#puzzleView",
          "type": "ref",
          "description": "The puzzle to solve. The player must find the continuation after the puzzle's first move (moves[0])."
        },
        "ranked": {
          "type": "boolean",
          "description": "Echoes whether this puzzle is scored."
        },
        "challenge": {
          "type": "string",
          "maxLength": 4096,
          "description": "Opaque signed token (JWT/HMAC/ed25519) encoding puzzleId, player DID, rating+RD snapshot, puzzle rating, nonce, and expiry. Passed back verbatim to submitAttempt. Empty for casual if you choose not to issue one."
        }
      }
    },
    "encoding": "application/json"
  },
  "description": "Fetches the next ranked puzzle for the authenticated player. Each puzzle needs to be solved or failed before requesting another; if the player already holds an unresolved ranked puzzle, that same puzzle (with a freshly re-signed challenge) is returned so a client that lost its token can recover it."
}

Lexicon Garden

@