Developer documentation ⌄

Publish Sudoku puzzles

Create hosted playable links and a public collection from your own verified grids. Each link encodes its puzzle, so it does not depend on a mutable puzzle record.

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. Duplicate supplied grids are preserved.

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.

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

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