Developer documentation ⌄
Create a Sudoku worksheet pack
Generate puzzles, verify uniqueness, prepare branded worksheets and answer sheets, and return a playable link for each puzzle in one request.
/api/v1/packsRequest 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- Measured technique level: beginner uses naked singles; easy requires hidden singles; medium requires locked candidates; hard requires naked pairs; expert remains unsolved by this ladder. No solve-time or specific expert-technique claim.
beginnereasymediumhardexpert seedstringoptional- Optional 1–128 character seed. The same seed, difficulty, count and generatorVersion reproduce puzzle content. Not secret; do not put personal data here. Omit for fresh random generation.
generatorVersionstringoptional- Optional reproducibility contract; currently seed-v1. Pin this with seed and retain returned puzzle content for archival use. Download tokens and PDF metadata are not reproducible.
seed-v1 includeAnswersbooleanoptional · default true- Append separate answer pages using the selected puzzles-per-page layout. Puzzle pages come first, then answer pages in matching order.
paperstringoptional · default a4- PDF page format: A4 (595.28 × 841.89 pt) or US Letter (612 × 792 pt).
a4letter optionsobjectoptional- Optional custom PDF layout. Keeps the Sudokumax design and attribution.
Show 2 properties
titlestring- 1–64 printable ASCII characters. Fitted to the page width.
puzzlesPerPageinteger- 1, 2 or 4 puzzles per page. Answer pages use the same layout and matching order.
Response fields
200 OK · application/json
engineVersionstring- Version of the engine used to verify the grids.
collectionIdstring- Hosted responses use a short c1- identifier backed by persistent public-grid storage. Legacy v1- links still work. Preserve the whole identifier.
collectionUrlstring (URL)- Public page listing all puzzles in this collection.
puzzles[].puzzlestring- Normalized 81-cell grid.
puzzles[].idstring- Versioned, self-contained puzzle identifier.
puzzles[].playableUrlstring (URL)- Hosted game containing this exact puzzle.
puzzles[].attributionobject- The mandatory credit travels with each puzzle when you separate the batch.
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.
generationobject- Present for seeded requests: seed and generatorVersion (seed-v1).
puzzles[].solutionstring- 81 digits containing the unique answer. Keep this on your server if players should not see it.
puzzles[].requestedDifficultystring- Requested technique level; guaranteed to match analysis.difficulty. The legacy analysis.rating remains a separate singles-only summary.
puzzles[].analysisobject- clueCount, rating, method, techniques, solvedWithSupportedTechniques, remainingCells, explanation, puzzle, unique and engineVersion. See Analyze difficulty for all definitions.
Show 13 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.
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.
optionsobject- Present when custom export options were supplied; contains applied title and puzzlesPerPage.
pdfUrlstring (URL)- Downloadable PDF link with a PDF-only access grant. Valid for 24 hours; key revocation or account suspension blocks it immediately.
pdfExpiresAtstring (ISO 8601)- UTC expiration timestamp for this download link. Re-export after it expires.
paperstring- Applied paper format, a4 or letter.
includeAnswersboolean- Whether the PDF includes separate answer sheets.
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
- For twenty beginner worksheets with answers, set count=20, difficulty=beginner and includeAnswers=true. With the default one-puzzle-per-page layout, the resulting PDF has 40 pages.
- Use /generate if your app only needs grid data. Use /worksheets if you already have the grids.
- Every puzzle and answer sheet carries the required website credit. Preserve that credit in all published online and offline outputs.
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>Download the PDF
Fetch the returned pdfUrl with GET. It contains a PDF-only grant, valid until pdfExpiresAt. The download returns application/pdf. Never replace the grant with an API key in the URL.
Alternatively, use your Bearer key with GET /api/v1/worksheets/{collectionId}?answers=1&paper=a4. Parameters: answers accepts 0 or 1 (default 1); paper accepts a4 or letter (default a4). The collection ID comes from this response.
An expired grant or revoked account/key returns 403. Invalid options return 400; a malformed ID returns 404. Re-export to renew the download link. Playable links remain public.
Request
Set SUDOKUMAX_API_KEY in your server environment. Examples never include your secret key.
curl https://sudokumax.com/api/v1/packs \
-H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"count": 1,
"difficulty": "beginner",
"includeAnswers": true,
"paper": "a4"
}'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. PDF grants and expiration are placeholders; send a request for working downloads.
{
"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"
},
"engineVersion": "1.2.0",
"collectionId": "v1-530070000600195000098000060800060003400803001700020006060000280000419005000080079",
"collectionUrl": "https://sudokumax.com/collections/v1-530070000600195000098000060800060003400803001700020006060000280000419005000080079",
"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.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"
},
"id": "v1-530070000600195000098000060800060003400803001700020006060000280000419005000080079",
"playableUrl": "https://sudokumax.com/puzzles/v1-530070000600195000098000060800060003400803001700020006060000280000419005000080079"
}
],
"includeAnswers": true,
"paper": "a4",
"pdfUrl": "https://sudokumax.com/api/v1/worksheets/v1-530070000600195000098000060800060003400803001700020006060000280000419005000080079?answers=1&paper=a4&download=EXAMPLE_DOWNLOAD_GRANT",
"pdfExpiresAt": "2026-10-06T12:00:00.000Z"
}