Developer documentation ⌄
Get a Sudoku hint
Return one explained placement for the current board, with optional locked-candidate and naked-pair reasoning. Distinguish incorrect progress, completed puzzles and positions that require unsupported techniques.
/api/v1/hintRequest 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.
strategystringoptional · default singles- singles keeps the original behaviour. logical also applies locked candidates and naked pairs, explaining every elimination before the next placement.
singleslogical
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.
coordinateBaseinteger- Always 0. Cell indices and programmatic coordinates are zero-based.
changedGivensinteger[]- Original clues changed or erased by the player. Zero-based indices 0–80.
incorrectCellsinteger[]- Incorrect filled entries in originally empty cells. Original clues are reported only in changedGivens, whether overwritten or erased. 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.
deductionsobject[]- Ordered elimination proofs. Each has technique (locked-candidates or naked-pair), sourceCells (zero-based indices), removedCandidates (index/value pairs) and explanation. Replay these before interpreting the placement candidates. Empty when no elimination is needed. May be nonempty with unsupported if no final placement follows.
statusstring- Only hint includes a placement; deductions may also be returned with unsupported. All four states are successful HTTP 200 responses.
hintinvalid-progresscompleteunsupported explanationstring- Readable explanation. Row, column and unit numbers in this prose are one-based.
hintobject | null- Null unless status is hint. Apply the returned value to the indicated index, then submit your updated progress for the next hint.
Show 10 properties
indexinteger- Zero-based cell index 0–80.
rowinteger- Zero-based row 0–8.
columninteger- Zero-based column 0–8.
coordinateBaseinteger- Always 0 for index, row, column and unit.index.
rowNumberinteger- Human row number, 1–9; matches the explanation.
columnNumberinteger- Human column number, 1–9; matches the explanation.
valueinteger- Digit 1–9 to place.
techniquestring- naked-single or hidden-single.
candidatesinteger[]- Candidates remaining in this cell after the returned deductions and before placing the hint.
unitobject | null- For hidden singles: type is row, column or box; index is 0–8. Boxes are numbered left to right, top to bottom. Null for naked singles.
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
- Default strategy=singles supports naked and hidden singles. strategy=logical also explains locked candidates and naked pairs. Expert positions may still return unsupported with hint=null; the API never guesses.
- Incorrect entries or changed givens return invalid-progress. Correct the indicated cells before asking again.
- Each request verifies the original puzzle. Rate limits still apply when no placement is returned.
Errors
422 CONFLICTING_GIVENS / UNSOLVABLE / MULTIPLE_SOLUTIONS / SEARCH_LIMIT / DUPLICATE_PUZZLE / COMPLETED_GRID
Specific grid failure; publishing/exporting also rejects duplicate grids and grids without blanks. 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>Request
Set SUDOKUMAX_API_KEY in your server environment. Examples never include your secret key.
curl https://sudokumax.com/api/v1/hint \
-H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"puzzle": "530070000600195000098000060800060003400803001700020006060000280000419005000080079",
"progress": "530070000600195000098000060800060003400803001700020006060000280000419005000080079"
}'Try this endpoint
Get an API key ↗Runs a real request. Calls are free.
The request example above updates as you edit these fields.
Response
Illustrative 200 response for one known puzzle. Send a request to inspect your own result.
{
"engineVersion": "1.2.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,
"coordinateBase": 0,
"changedGivens": [],
"incorrectCells": [],
"conflictCells": [],
"deductions": [],
"status": "hint",
"hint": {
"index": 40,
"row": 4,
"column": 4,
"rowNumber": 5,
"columnNumber": 5,
"coordinateBase": 0,
"value": 5,
"technique": "naked-single",
"candidates": [
5
],
"unit": null
},
"explanation": "Row 5, column 5 has only one candidate: 5.",
"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"
}
}