org.lichess.puzzle.submitAttempt

pds.dad

Documentation

Submits the outcome of a ranked puzzle previously issued by getNextRanked. The challenge token issued with the puzzle must be passed back verbatim, along with the full solution line the player played. The server validates those moves against the puzzle's actual solution: the attempt counts as solved only if they match. Applies the Glicko-2 rating update and returns the player's new rating, plus a detached signature (sig) proving the server judged the moves; the client should store it in its org.lichess.puzzle.attempt record. Resubmitting the same challenge (same nonce) is idempotent and returns the original result.

main procedure

Submits the outcome of a ranked puzzle previously issued by getNextRanked. The challenge token issued with the puzzle must be passed back verbatim, along with the full solution line the player played. The server validates those moves against the puzzle's actual solution: the attempt counts as solved only if they match. Applies the Glicko-2 rating update and returns the player's new rating, plus a detached signature (sig) proving the server judged the moves; the client should store it in its org.lichess.puzzle.attempt record. Resubmitting the same challenge (same nonce) is idempotent and returns the original result.

Input

Encodingapplication/json
challenge string Required

The opaque signed token issued by getNextRanked, passed back verbatim.

maxLength: 4096 bytes
solutionMoves string Required

The full solution line the player played, in the same notation and form as the puzzle's solution moves (org.lichess.puzzle.defs#puzzleView moves). The server compares this against the puzzle's actual solution to decide whether the attempt is solved.

Output

Encodingapplication/json
attestation reforg.lichess.puzzle.defs#resultAttestation Optional

The exact payload sig signs, echoed back so callers can see and independently verify what was attested. Present only when the attempt was rated (ranked and not flagged).

nonce string Required

The nonce (jti) of the challenge this result resolves. Store it in the attempt record's nonce field so duplicate records are detectable.

ranked boolean Required

Whether this attempt counted towards the player's rating.

rating integer Required

The player's Glicko-2 rating after applying this attempt.

ratingDeviation integer Required

The player's Glicko-2 rating deviation after applying this attempt.

sig string Optional

base64url (unpadded) detached signature by the service over the canonical DAG-CBOR encoding of attestation (see org.lichess.puzzle.defs#resultAttestation). Present only when the attempt was rated (ranked and not flagged). Store it verbatim in the attempt record's sig field.

solved boolean Required

Whether the submitted solution line matched the puzzle's actual solution, as judged by the server.

Errors

InvalidChallenge The challenge token is malformed, has a bad signature, or does not belong to the authenticated player.
ChallengeExpired The challenge token is past its expiry. Request a new puzzle.
UnknownAttempt No outstanding attempt matches this challenge.
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://bsky.social)
Enter valid JSON for the request body
View raw schema 
{
  "type": "procedure",
  "input": {
    "schema": {
      "type": "object",
      "required": [
        "challenge",
        "solutionMoves"
      ],
      "properties": {
        "challenge": {
          "type": "string",
          "maxLength": 4096,
          "description": "The opaque signed token issued by getNextRanked, passed back verbatim."
        },
        "solutionMoves": {
          "type": "string",
          "description": "The full solution line the player played, in the same notation and form as the puzzle's solution moves (org.lichess.puzzle.defs#puzzleView moves). The server compares this against the puzzle's actual solution to decide whether the attempt is solved."
        }
      }
    },
    "encoding": "application/json"
  },
  "errors": [
    {
      "name": "InvalidChallenge",
      "description": "The challenge token is malformed, has a bad signature, or does not belong to the authenticated player."
    },
    {
      "name": "ChallengeExpired",
      "description": "The challenge token is past its expiry. Request a new puzzle."
    },
    {
      "name": "UnknownAttempt",
      "description": "No outstanding attempt matches this challenge."
    }
  ],
  "output": {
    "schema": {
      "type": "object",
      "required": [
        "rating",
        "ratingDeviation",
        "ranked",
        "solved",
        "nonce"
      ],
      "properties": {
        "sig": {
          "type": "string",
          "maxLength": 128,
          "description": "base64url (unpadded) detached signature by the service over the canonical DAG-CBOR encoding of attestation (see org.lichess.puzzle.defs#resultAttestation). Present only when the attempt was rated (ranked and not flagged). Store it verbatim in the attempt record's sig field."
        },
        "nonce": {
          "type": "string",
          "maxLength": 64,
          "description": "The nonce (jti) of the challenge this result resolves. Store it in the attempt record's nonce field so duplicate records are detectable."
        },
        "ranked": {
          "type": "boolean",
          "description": "Whether this attempt counted towards the player's rating."
        },
        "rating": {
          "type": "integer",
          "description": "The player's Glicko-2 rating after applying this attempt."
        },
        "solved": {
          "type": "boolean",
          "description": "Whether the submitted solution line matched the puzzle's actual solution, as judged by the server."
        },
        "attestation": {
          "ref": "org.lichess.puzzle.defs#resultAttestation",
          "type": "ref",
          "description": "The exact payload sig signs, echoed back so callers can see and independently verify what was attested. Present only when the attempt was rated (ranked and not flagged)."
        },
        "ratingDeviation": {
          "type": "integer",
          "description": "The player's Glicko-2 rating deviation after applying this attempt."
        }
      }
    },
    "encoding": "application/json"
  },
  "description": "Submits the outcome of a ranked puzzle previously issued by getNextRanked. The challenge token issued with the puzzle must be passed back verbatim, along with the full solution line the player played. The server validates those moves against the puzzle's actual solution: the attempt counts as solved only if they match. Applies the Glicko-2 rating update and returns the player's new rating, plus a detached signature (sig) proving the server judged the moves; the client should store it in its org.lichess.puzzle.attempt record. Resubmitting the same challenge (same nonce) is idempotent and returns the original result."
}

Lexicon Garden

@