Skip to content
Developer documentation ⌄
DevelopersAPI reference

Publish Sudoku puzzles

Create hosted playable links and a public collection from your own verified grids. Individual playable links encode the grid. Hosted collection links use a compact identifier backed by persistent storage.

POST/api/v1/publish
Bearer API key requiredContent-Type: application/jsonMCP: publish_puzzles

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.

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

  • Anyone with a full link can open it. Published grids have no privacy controls, expiry, edit operation or recall mechanism.
  • URLs remain usable while Sudokumax hosts the versioned routes. Revoking a key blocks new API requests, not already published links.
  • Publishing does not create a PDF. Pass the same grids to /worksheets if you need print exports.

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 →

Request

Set SUDOKUMAX_API_KEY in your server environment. Examples never include your secret key.

curl https://sudokumax.com/api/v1/publish \
  -H "Authorization: Bearer $SUDOKUMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "puzzles": [
    "530070000600195000098000060800060003400803001700020006060000280000419005000080079"
  ]
}'

Response

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

{
  "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"
    }
  ]
}