Developer documentation ⌄
Analyze Sudoku difficulty
Verify uniqueness and measure the hardest technique reached by a deterministic solver: singles, locked candidates and naked pairs. Expert means further techniques are needed.
/api/v1/analyzeRequest 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.
Response fields
200 OK · application/json
puzzlestring- Normalized 81-cell grid; blanks are -.
engineVersionstring- Version of the shared Sudoku engine.
uniqueboolean- Always true for a successful analysis. Ambiguous or unsolved inputs receive HTTP 422.
clueCountinteger- Number of given digits in the original puzzle.
ratingstring- beginner: solved with supported singles; beyond-singles: further techniques needed; complete: no blank cells.
difficultystring- Measured level: beginner=naked singles, easy=hidden singles, medium=locked candidates, hard=naked pairs, expert=beyond this ladder. Generated puzzles always match requestedDifficulty. Completed grids return beginner here and rating=complete.
techniqueCountsobject- Counts of nakedSingles and hiddenSingles placements, plus productive lockedCandidates and nakedPairs elimination steps in the full technique ladder.
techniqueRemainingCellsinteger- Unfilled cells after the full ladder. Greater than zero for expert; zero for the other levels.
methodstring- techniques-v2. Deterministic order: naked singles, hidden singles, locked candidates, naked pairs. The legacy rating/techniques/remainingCells fields still describe singles only.
techniquesobject- nakedSingles and hiddenSingles: number of placements made using each technique.
Show 2 properties
nakedSinglesinteger- Placements where a cell had one remaining candidate.
hiddenSinglesinteger- Placements where a digit had only one possible position in a row, column or box.
solvedWithSupportedTechniquesboolean- Whether naked and hidden singles completed the grid.
remainingCellsinteger- Cells left blank after supported techniques are exhausted.
explanationstring- Human-readable explanation of the rating and its limits.
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
- Use difficulty for the five measured levels. The legacy rating and techniques summarize singles only. Human experience varies; expert is an open-ended category beyond the supported ladder, not a claim about a particular advanced technique.
- A completed valid grid returns rating=complete. Analysis does not return step-by-step hints.
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/analyze \
-H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"puzzle": "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",
"unique": true,
"clueCount": 30,
"rating": "beginner",
"method": "techniques-v2",
"difficulty": "beginner",
"techniqueCounts": {
"nakedSingles": 51,
"hiddenSingles": 0,
"lockedCandidates": 0,
"nakedPairs": 0
},
"techniqueRemainingCells": 0,
"techniques": {
"nakedSingles": 51,
"hiddenSingles": 0
},
"solvedWithSupportedTechniques": true,
"remainingCells": 0,
"explanation": "The legacy rating describes singles only. difficulty reports the hardest technique used by the deterministic technique ladder; it is not a solve-time estimate.",
"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"
}
}