Skip to content
Developer documentation ⌄
DevelopersAPI reference

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.

POST/api/v1/analyze
Bearer API key requiredContent-Type: application/jsonMCP: analyze_difficulty

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.

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>
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/analyze \
  -H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "puzzle": "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",
  "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"
  }
}