Skip to content
SudokumaxSudokumax
Developer documentation ⌄
DevelopersAPI reference

Generate Sudoku puzzles

Get unique Sudoku puzzles and their solutions for your own app or website. Every generated grid is independently verified before it is returned.

POST/api/v1/generate
Bearer API key requiredContent-Type: application/jsonMCP: generate_puzzles

Request body

Send a JSON object. Unknown fields are rejected.

countintegeroptional · default 1
Number of distinct puzzles in this batch. Integer from 1 to 20.
difficultystringoptional · default beginner
Requested generator difficulty. Beginner is additionally verified solvable with naked and hidden singles.
beginnereasymediumhardexpert

Response fields

200 OK · application/json

engineVersionstring
Version of the shared generator and verifier.
puzzles[].puzzlestring
81 cells; digits 1–9 are givens and - is a blank. Render this in your game UI.
puzzles[].solutionstring
81 digits containing the unique answer. Keep this on your server if players should not see it.
puzzles[].requestedDifficultystring
The requested generator label. This is separate from the measured analysis rating.
puzzles[].analysisobject
clueCount, rating, method, techniques, solvedWithSupportedTechniques, remainingCells, explanation, puzzle, unique and engineVersion. See Analyze difficulty for all definitions.
Show 10 properties
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.
puzzles[].attributionobject
Mandatory Sudokumax credit for this puzzle.
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.
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

  • Generated puzzles are distinct within one batch. Separate requests may return the same grid; cross-request uniqueness is not guaranteed.
  • This endpoint does not create hosted links or a PDF. Use /publish for playable links or /packs for the complete worksheet workflow.
  • Build your own player UI and store progress in your app. Use /validate and /hint for board feedback and singles hints. This API does not manage player accounts, scoring, timers or saved games.

Errors

503 GENERATION_LIMIT
The bounded generator could not complete the requested batch. Retry later or request fewer puzzles.

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/generate \
  -H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "count": 1,
  "difficulty": "beginner"
}'

Response

Illustrative 200 response for one known puzzle. Send a request to inspect your own result.

{
  "engineVersion": "1.0.0",
  "puzzles": [
    {
      "puzzle": "53--7----6--195----98----6-8---6---34--8-3--17---2---6-6----28----419--5----8--79",
      "solution": "534678912672195348198342567859761423426853791713924856961537284287419635345286179",
      "requestedDifficulty": "beginner",
      "analysis": {
        "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"
      }
    }
  ],
  "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"
  }
}