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.

POST/api/v1/packs

Bearer API key requiredContent-Type: application/jsonMCP: create_worksheet_pack

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
includeAnswersbooleanoptional · default true: Append a separate answer page for each puzzle. 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

Response fields

200 OK · application/json

engineVersionstring

Version of the engine used to verify the grids.

collectionIdstring

Versioned identifier containing all grids. Preserve the whole value.

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.

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.

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. 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>

Free pricing & attribution rules →

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"
}'

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.0.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.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"
      },
      "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"
}