Skip to content
Developer documentation ⌄
DevelopersAPI reference

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.

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.
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>
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.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"
  }
}