Skip to content
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. Each grid must have at least one blank. Repeated normalized grids fail with DUPLICATE_PUZZLE.
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.
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

  • 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 CONFLICTING_GIVENS / UNSOLVABLE / MULTIPLE_SOLUTIONS / SEARCH_LIMIT / DUPLICATE_PUZZLE / COMPLETED_GRID
Specific grid failure; publishing/exporting also rejects duplicate grids and grids without blanks. 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.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",
      "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"
}