Skip to content
SudokumaxSudokumax
Developer documentation ⌄
DevelopersAPI reference

Validate Sudoku progress

Check a player board without returning the full solution. Identify changed givens, incorrect entries and row, column or box conflicts, and verify completion.

POST/api/v1/validate
Bearer API key requiredContent-Type: application/jsonMCP: validate_progress

Request body

Send a JSON object. Unknown fields are rejected.

puzzlestringrequired
Exactly 81 cells in row order. Digits 1–9 are givens; 0, . and - are accepted as blanks. Whitespace is not accepted.
progressstringrequired
Current player board: exactly 81 cells in row order. Include the original givens. Use 0, . or - for blanks.

Response fields

200 OK · application/json

engineVersionstring
Shared engine version.
puzzlestring
Normalized original puzzle.
progressstring
Normalized current board.
validboolean
True when all givens are preserved and every filled cell matches the unique solution.
completeboolean
True only when all 81 cells are filled correctly.
remainingCellsinteger
Blank cells in the submitted board, including any erased givens.
changedGivensinteger[]
Original clues changed or erased by the player. Zero-based indices 0–80.
incorrectCellsinteger[]
Filled cells that differ from the verified solution. Zero-based indices 0–80.
conflictCellsinteger[]
All filled cells participating in duplicate digits in a row, column or box, including givens. Sorted, zero-based indices.
attributionobject
Required credit: required=true, text, url, html, offlineText and termsUrl. Display a visible hyperlink online and a legible website address on printed outputs.
Show 6 properties
requiredboolean
Always true. Attribution is a condition of free access.
textstring
Visible credit: Created with Sudokumax.
urlstring (URL)
Canonical credit destination: https://sudokumax.com.
htmlstring
Ready-to-use HTML link. Keep it visible alongside the puzzle.
offlineTextstring
Credit and website address to print on each published item.
termsUrlstring (URL)
Full API attribution terms.

Behavior

  • Incorrect progress returns HTTP 200 with valid=false. Only an invalid or non-unique original puzzle produces 422.
  • Cell indices, rows and columns are zero-based. A locally legal move can still be incorrect for the unique solution.
  • This operation is stateless. Your app stores progress, applies moves and decides when to reveal feedback.

Errors

422 NOT_UNIQUE
A grid is invalid, unsolvable or ambiguous. No partial export is returned.

422 SEARCH_LIMIT
The uniqueness check exhausted its budget. Retry with a grid that can be verified.

All endpoints also return structured errors for invalid input, missing keys, revoked access and rate limits.

Full error reference →

Attribution

Every published output must credit Sudokumax. Use a visible hyperlink online; print the website address offline.

<a href="https://sudokumax.com">Created with Sudokumax</a>
Free pricing & attribution rules →

Request

Set SUDOKUMAX_API_KEY in your server environment. Examples never include your secret key.

curl https://sudokumax.com/api/v1/validate \
  -H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "puzzle": "530070000600195000098000060800060003400803001700020006060000280000419005000080079",
  "progress": "530070000600195000098000060800060003400803001700020006060000280000419005000080079"
}'

Response

Illustrative 200 response for one known puzzle. Send a request to inspect your own result.

{
  "engineVersion": "1.0.0",
  "puzzle": "53--7----6--195----98----6-8---6---34--8-3--17---2---6-6----28----419--5----8--79",
  "progress": "53--7----6--195----98----6-8---6---34--8-3--17---2---6-6----28----419--5----8--79",
  "valid": true,
  "complete": false,
  "remainingCells": 51,
  "changedGivens": [],
  "incorrectCells": [],
  "conflictCells": [],
  "attribution": {
    "required": true,
    "text": "Created with Sudokumax",
    "url": "https://sudokumax.com",
    "html": "<a href=\"https://sudokumax.com\">Created with Sudokumax</a>",
    "offlineText": "Created with Sudokumax · sudokumax.com",
    "termsUrl": "https://sudokumax.com/developers/terms"
  }
}