Skip to content
SudokumaxSudokumax
Developer documentation ⌄
DevelopersAPI reference

Export Sudoku worksheets

Turn supplied grids into a Sudokumax-styled PDF with one puzzle per page, optional answer sheets, QR codes and playable links.

POST/api/v1/worksheets
Bearer API key requiredContent-Type: application/jsonMCP: export_worksheets

Request body

Send a JSON object. Unknown fields are rejected.

puzzlesstring[]required
1–20 grids, each exactly 81 cells. Each must have exactly one verified solution. Duplicate supplied grids are preserved.
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.
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

  • All grids must be verified unique. A single invalid grid fails the request; no partial PDF is returned.
  • The JSON response contains a download URL, not PDF bytes. Fetch pdfUrl to download application/pdf.
  • PDFs have the same logo, navy typography and restrained grid styling as the website. The website credit appears on every puzzle and answer page; retain it when republishing.

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 →

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/worksheets \
  -H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "puzzles": [
    "530070000600195000098000060800060003400803001700020006060000280000419005000080079"
  ],
  "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",
      "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"
}