Skip to content
SudokumaxSudokumax
Developer documentation ⌄
DevelopersAPI reference

Get a Sudoku hint

Return one explained naked or hidden single for the current board. Distinguish incorrect progress, completed puzzles and positions that require unsupported techniques.

POST/api/v1/hint
Bearer API key requiredContent-Type: application/jsonMCP: get_hint

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.
statusstring
Only hint includes a placement. 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 7 properties
indexinteger
Zero-based cell index 0–80.
rowinteger
Zero-based row 0–8.
columninteger
Zero-based column 0–8.
valueinteger
Digit 1–9 to place.
techniquestring
naked-single or hidden-single.
candidatesinteger[]
Legal candidates in this cell 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

  • Only naked and hidden singles are supported. Unsupported positions return hint=null; no guessing or full-solution reveal.
  • 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 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/hint \
  -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": [],
  "status": "hint",
  "hint": {
    "index": 40,
    "row": 4,
    "column": 4,
    "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"
  }
}