Skip to content
SudokumaxSudokumax
Developer documentation ⌄
DevelopersAPI reference

Check Sudoku uniqueness

Count up to two solutions for a supplied grid. Distinguishes conflicting givens, unsolvable puzzles, multiple solutions and searches that could not finish.

POST/api/v1/check
Bearer API key requiredContent-Type: application/jsonMCP: check_uniqueness

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 input grid.
statusstring
unique, multiple, unsolvable, invalid, or unknown.
uniqueboolean | null
true only for exactly one verified solution. false when disproved; null if the search budget was exhausted.
solutionstring | null
The 81-digit answer when verified unique. Otherwise null.
solutionsFoundinteger
0, 1 or 2; the solver stops once a second solution is found. With status unknown this is only a partial count.
searchCompleteboolean
Whether the search reached a conclusive result.
nodesinteger
Search nodes visited within the bounded work budget.
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

  • Conflicting givens are a successful HTTP 200 check with status invalid; malformed input syntax returns HTTP 400.
  • Do not interpret solutionsFound=1 as proof of uniqueness. Require unique=true.
  • The solver stops at 100,000 nodes or a 250 ms deadline checked every 128 nodes. Budget exhaustion returns unknown, never a guessed result.

Errors

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/check \
  -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.

{
  "puzzle": "53--7----6--195----98----6-8---6---34--8-3--17---2---6-6----28----419--5----8--79",
  "status": "unique",
  "unique": true,
  "solutionsFound": 1,
  "searchComplete": true,
  "nodes": 52,
  "solution": "534678912672195348198342567859761423426853791713924856961537284287419635345286179",
  "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"
  }
}