Skip to content
SudokumaxSudokumax
Developer documentation ⌄
DevelopersAPI reference

Analyze Sudoku difficulty

Verify a grid is unique, then attempt to solve it using naked and hidden singles. Get a transparent technique report rather than an unsupported difficulty claim.

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.
methodstring
singles-v1. Identifies the supported technique analysis, not a universal difficulty scale.
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

  • This is a singles-only analysis. “Beyond singles” does not mean “hard” or “expert”; those ratings need additional techniques and calibration.
  • A completed valid grid returns rating=complete. Analysis does not return step-by-step hints.

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/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.0.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": "singles-v1",
  "techniques": {
    "nakedSingles": 51,
    "hiddenSingles": 0
  },
  "solvedWithSupportedTechniques": true,
  "remainingCells": 0,
  "explanation": "Solvable using naked and hidden singles only. This is a conservative technique rating, 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"
  }
}