{"openapi":"3.1.0","info":{"title":"Sudokumax Puzzle API","version":"1.2.0","description":"Generate verified Sudoku worksheets, downloadable PDFs and stable playable links and short hosted collection links. Free with mandatory attribution. API key required. Online outputs must visibly hyperlink to https://sudokumax.com; offline outputs must print sudokumax.com. Maximum 20 puzzles per batch and 16 KiB request bodies. 6000 authenticated requests per account per minute, with additional per-instance limits. PDF download links expire after 24 hours and are disabled when their key or account is revoked. Difficulty is verified with a deterministic technique ladder: beginner=naked singles, easy=hidden singles, medium=locked candidates, hard=naked pairs, expert=requires techniques beyond that ladder. Expert does not identify a specific advanced technique. Batch grids are non-equivalent under standard Sudoku symmetries. Developer accounts manage access; published puzzle links are public. The daily JavaScript widget does not consume the API quota.","contact":{"url":"https://sudokumax.com/developers"}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://sudokumax.com/api/v1"}],"paths":{"/generate":{"post":{"operationId":"generate","summary":"Generate verified puzzles","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"count":{"default":1,"type":"integer","minimum":1,"maximum":20},"difficulty":{"default":"beginner","type":"string","enum":["beginner","easy","medium","hard","expert"]},"seed":{"type":"string","minLength":1,"maxLength":128},"generatorVersion":{"type":"string","const":"seed-v1"}},"additionalProperties":false}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"generation":{"type":"object","properties":{"seed":{"type":"string"},"generatorVersion":{"const":"seed-v1"}},"required":["seed","generatorVersion"]},"engineVersion":{"type":"string"},"puzzles":{"type":"array","items":{"type":"object","properties":{"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}},"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"solution":{"type":"string","pattern":"^[1-9]{81}$"},"requestedDifficulty":{"enum":["beginner","easy","medium","hard","expert"]},"analysis":{"type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"engineVersion":{"type":"string"},"unique":{"const":true},"clueCount":{"type":"integer"},"rating":{"enum":["beginner","beyond-singles","complete"]},"method":{"const":"techniques-v2"},"difficulty":{"enum":["beginner","easy","medium","hard","expert"]},"techniqueCounts":{"type":"object","properties":{"nakedSingles":{"type":"integer"},"hiddenSingles":{"type":"integer"},"lockedCandidates":{"type":"integer"},"nakedPairs":{"type":"integer"}},"required":["nakedSingles","hiddenSingles","lockedCandidates","nakedPairs"]},"techniqueRemainingCells":{"type":"integer"},"techniques":{"type":"object","properties":{"nakedSingles":{"type":"integer"},"hiddenSingles":{"type":"integer"}},"required":["nakedSingles","hiddenSingles"]},"solvedWithSupportedTechniques":{"type":"boolean"},"remainingCells":{"type":"integer"},"explanation":{"type":"string"}},"required":["puzzle","engineVersion","unique","clueCount","rating","method","difficulty","techniqueCounts","techniqueRemainingCells","techniques","solvedWithSupportedTechniques","remainingCells","explanation"]}},"required":["attribution","puzzle","solution","requestedDifficulty","analysis"]}},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["engineVersion","puzzles","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/check":{"post":{"operationId":"check","summary":"Check uniqueness","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9.0-]{81}$"}},"required":["puzzle"],"additionalProperties":false}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"status":{"enum":["unique","multiple","unsolvable","invalid","unknown"]},"unique":{"type":["boolean","null"]},"solutionsFound":{"type":"integer","minimum":0,"maximum":2},"searchComplete":{"type":"boolean"},"nodes":{"type":"integer"},"conflictCells":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"solution":{"type":["string","null"]},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["puzzle","status","unique","solutionsFound","searchComplete","nodes","conflictCells","solution","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/analyze":{"post":{"operationId":"analyze","summary":"Analyze solving techniques","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9.0-]{81}$"}},"required":["puzzle"],"additionalProperties":false}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"engineVersion":{"type":"string"},"unique":{"const":true},"clueCount":{"type":"integer"},"rating":{"enum":["beginner","beyond-singles","complete"]},"method":{"const":"techniques-v2"},"difficulty":{"enum":["beginner","easy","medium","hard","expert"]},"techniqueCounts":{"type":"object","properties":{"nakedSingles":{"type":"integer"},"hiddenSingles":{"type":"integer"},"lockedCandidates":{"type":"integer"},"nakedPairs":{"type":"integer"}},"required":["nakedSingles","hiddenSingles","lockedCandidates","nakedPairs"]},"techniqueRemainingCells":{"type":"integer"},"techniques":{"type":"object","properties":{"nakedSingles":{"type":"integer"},"hiddenSingles":{"type":"integer"}},"required":["nakedSingles","hiddenSingles"]},"solvedWithSupportedTechniques":{"type":"boolean"},"remainingCells":{"type":"integer"},"explanation":{"type":"string"},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["puzzle","engineVersion","unique","clueCount","rating","method","difficulty","techniqueCounts","techniqueRemainingCells","techniques","solvedWithSupportedTechniques","remainingCells","explanation","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/validate":{"post":{"operationId":"validate","summary":"Validate a player board","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9.0-]{81}$"},"progress":{"type":"string","pattern":"^[1-9.0-]{81}$"}},"required":["puzzle","progress"],"additionalProperties":false}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"engineVersion":{"type":"string"},"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"progress":{"type":"string","pattern":"^[1-9-]{81}$"},"valid":{"type":"boolean"},"complete":{"type":"boolean"},"remainingCells":{"type":"integer","minimum":0,"maximum":81},"coordinateBase":{"const":0},"changedGivens":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"incorrectCells":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"conflictCells":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["engineVersion","puzzle","progress","valid","complete","remainingCells","coordinateBase","changedGivens","incorrectCells","conflictCells","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/hint":{"post":{"operationId":"hint","summary":"Get an explained Sudoku hint","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9.0-]{81}$"},"progress":{"type":"string","pattern":"^[1-9.0-]{81}$"},"strategy":{"default":"singles","type":"string","enum":["singles","logical"]}},"required":["puzzle","progress"],"additionalProperties":false}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"engineVersion":{"type":"string"},"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"progress":{"type":"string","pattern":"^[1-9-]{81}$"},"valid":{"type":"boolean"},"complete":{"type":"boolean"},"remainingCells":{"type":"integer","minimum":0,"maximum":81},"coordinateBase":{"const":0},"changedGivens":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"incorrectCells":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"conflictCells":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"deductions":{"type":"array","items":{"type":"object","properties":{"technique":{"enum":["locked-candidates","naked-pair"]},"sourceCells":{"type":"array","items":{"type":"integer","minimum":0,"maximum":80}},"removedCandidates":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":80},"value":{"type":"integer","minimum":1,"maximum":9}},"required":["index","value"]}},"explanation":{"type":"string"}},"required":["technique","sourceCells","removedCandidates","explanation"]}},"status":{"enum":["hint","complete","invalid-progress","unsupported"]},"explanation":{"type":"string"},"hint":{"anyOf":[{"type":"null"},{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":80},"row":{"type":"integer","minimum":0,"maximum":8},"column":{"type":"integer","minimum":0,"maximum":8},"coordinateBase":{"const":0},"rowNumber":{"type":"integer","minimum":1,"maximum":9},"columnNumber":{"type":"integer","minimum":1,"maximum":9},"value":{"type":"integer","minimum":1,"maximum":9},"technique":{"enum":["naked-single","hidden-single"]},"candidates":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9}},"unit":{"anyOf":[{"type":"null"},{"type":"object","properties":{"type":{"enum":["row","column","box"]},"index":{"type":"integer","minimum":0,"maximum":8}},"required":["type","index"]}]}},"required":["index","row","column","coordinateBase","rowNumber","columnNumber","value","technique","candidates","unit"]}]},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["engineVersion","puzzle","progress","valid","complete","remainingCells","coordinateBase","changedGivens","incorrectCells","conflictCells","deductions","status","explanation","hint","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/publish":{"post":{"operationId":"publish","summary":"Create playable and collection links","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"puzzles":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[1-9.0-]{81}$"}}},"required":["puzzles"],"additionalProperties":false}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"engineVersion":{"type":"string"},"collectionId":{"type":"string"},"collectionUrl":{"type":"string","format":"uri"},"puzzles":{"type":"array","items":{"type":"object","properties":{"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}},"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"id":{"type":"string"},"playableUrl":{"type":"string","format":"uri"}},"required":["attribution","puzzle","id","playableUrl"]}},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["engineVersion","collectionId","collectionUrl","puzzles","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worksheets":{"post":{"operationId":"worksheets","summary":"Export supplied puzzles to PDF","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"puzzles":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[1-9.0-]{81}$"}},"includeAnswers":{"default":true,"type":"boolean"},"paper":{"default":"a4","type":"string","enum":["a4","letter"]},"options":{"type":"object","properties":{"title":{"default":"Sudoku worksheets","type":"string","pattern":"^[ -~]{1,64}$"},"puzzlesPerPage":{"default":1,"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":4}]}},"additionalProperties":false}},"required":["puzzles"],"additionalProperties":false}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"engineVersion":{"type":"string"},"collectionId":{"type":"string"},"collectionUrl":{"type":"string","format":"uri"},"puzzles":{"type":"array","items":{"type":"object","properties":{"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}},"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"id":{"type":"string"},"playableUrl":{"type":"string","format":"uri"}},"required":["attribution","puzzle","id","playableUrl"]}},"options":{"type":"object","properties":{"title":{"type":"string"},"puzzlesPerPage":{"enum":[1,2,4]}},"required":["title","puzzlesPerPage"]},"pdfUrl":{"type":"string","format":"uri"},"pdfExpiresAt":{"type":"string","format":"date-time"},"includeAnswers":{"type":"boolean"},"paper":{"enum":["a4","letter"]},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["engineVersion","collectionId","collectionUrl","puzzles","pdfUrl","pdfExpiresAt","includeAnswers","paper","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/packs":{"post":{"operationId":"packs","summary":"Generate a complete worksheet pack","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"count":{"default":1,"type":"integer","minimum":1,"maximum":20},"difficulty":{"default":"beginner","type":"string","enum":["beginner","easy","medium","hard","expert"]},"seed":{"type":"string","minLength":1,"maxLength":128},"generatorVersion":{"type":"string","const":"seed-v1"},"includeAnswers":{"default":true,"type":"boolean"},"paper":{"default":"a4","type":"string","enum":["a4","letter"]},"options":{"type":"object","properties":{"title":{"default":"Sudoku worksheets","type":"string","pattern":"^[ -~]{1,64}$"},"puzzlesPerPage":{"default":1,"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":4}]}},"additionalProperties":false}},"additionalProperties":false},"example":{"count":20,"difficulty":"beginner","includeAnswers":true,"paper":"a4"}}}},"responses":{"200":{"headers":{"X-Request-Id":{"description":"Server-generated application request ID.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Authenticated account requests per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the account window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Window reset time, Unix seconds.","schema":{"type":"integer"}}},"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"engineVersion":{"type":"string"},"collectionId":{"type":"string"},"collectionUrl":{"type":"string","format":"uri"},"puzzles":{"type":"array","items":{"type":"object","properties":{"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}},"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"solution":{"type":"string","pattern":"^[1-9]{81}$"},"requestedDifficulty":{"enum":["beginner","easy","medium","hard","expert"]},"analysis":{"type":"object","properties":{"puzzle":{"type":"string","pattern":"^[1-9-]{81}$"},"engineVersion":{"type":"string"},"unique":{"const":true},"clueCount":{"type":"integer"},"rating":{"enum":["beginner","beyond-singles","complete"]},"method":{"const":"techniques-v2"},"difficulty":{"enum":["beginner","easy","medium","hard","expert"]},"techniqueCounts":{"type":"object","properties":{"nakedSingles":{"type":"integer"},"hiddenSingles":{"type":"integer"},"lockedCandidates":{"type":"integer"},"nakedPairs":{"type":"integer"}},"required":["nakedSingles","hiddenSingles","lockedCandidates","nakedPairs"]},"techniqueRemainingCells":{"type":"integer"},"techniques":{"type":"object","properties":{"nakedSingles":{"type":"integer"},"hiddenSingles":{"type":"integer"}},"required":["nakedSingles","hiddenSingles"]},"solvedWithSupportedTechniques":{"type":"boolean"},"remainingCells":{"type":"integer"},"explanation":{"type":"string"}},"required":["puzzle","engineVersion","unique","clueCount","rating","method","difficulty","techniqueCounts","techniqueRemainingCells","techniques","solvedWithSupportedTechniques","remainingCells","explanation"]},"id":{"type":"string"},"playableUrl":{"type":"string","format":"uri"}},"required":["attribution","puzzle","solution","requestedDifficulty","analysis","id","playableUrl"]}},"options":{"type":"object","properties":{"title":{"type":"string"},"puzzlesPerPage":{"enum":[1,2,4]}},"required":["title","puzzlesPerPage"]},"pdfUrl":{"type":"string","format":"uri"},"pdfExpiresAt":{"type":"string","format":"date-time"},"includeAnswers":{"type":"boolean"},"paper":{"enum":["a4","letter"]},"generation":{"type":"object","properties":{"seed":{"type":"string"},"generatorVersion":{"const":"seed-v1"}},"required":["seed","generatorVersion"]},"attribution":{"type":"object","required":["required","text","url","html","offlineText","termsUrl"],"properties":{"required":{"const":true},"text":{"const":"Created with Sudokumax"},"url":{"const":"https://sudokumax.com"},"html":{"const":"<a href=\"https://sudokumax.com\">Created with Sudokumax</a>"},"offlineText":{"const":"Created with Sudokumax · sudokumax.com"},"termsUrl":{"const":"https://sudokumax.com/developers/terms"}}}},"required":["engineVersion","collectionId","collectionUrl","puzzles","pdfUrl","pdfExpiresAt","includeAnswers","paper","attribution"]}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key or account disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported method; inspect Allow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 16 KiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Conflicting, unsolvable, ambiguous, duplicate or completed puzzle; inspect error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; inspect Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Generation budget exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/library/list":{"post":{"operationId":"library_list","summary":"List private puzzle metadata in this key’s personal or team library. Requires library:read. Paginated; does not publish anything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"default":20,"type":"integer","minimum":1,"maximum":50},"after":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Private library result.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"created":{"type":"number"},"updated":{"type":"number"}},"required":["id","name","tags","revision","created","updated"],"additionalProperties":false}},"nextCursor":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"attribution":{"type":"object","properties":{"text":{"type":"string","const":"Created with Sudokumax"},"url":{"type":"string","const":"https://sudokumax.com"},"required":{"type":"boolean","const":true}},"required":["text","url","required"],"additionalProperties":{}}},"required":["entries","nextCursor","attribution"],"additionalProperties":false}}}},"400":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or disabled access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision conflict or library capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/library/get":{"post":{"operationId":"library_get","summary":"Read a saved private puzzle and its answer by ID. Requires library:read. Keep the answer server-side.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Private library result.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"puzzle":{"type":"string"},"solution":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"created":{"type":"number"},"updated":{"type":"number"}},"required":["id","name","puzzle","solution","tags","revision","created","updated"],"additionalProperties":false},"attribution":{"type":"object","properties":{"text":{"type":"string","const":"Created with Sudokumax"},"url":{"type":"string","const":"https://sudokumax.com"},"required":{"type":"boolean","const":true}},"required":["text","url","required"],"additionalProperties":{}}},"required":["entry","attribution"],"additionalProperties":false}}}},"400":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or disabled access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision conflict or library capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/library/save":{"post":{"operationId":"library_save","summary":"Save a verified puzzle privately with a name and tags. Requires library:write. To update, supply both id and current revision. No public link is created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"name":{"type":"string","minLength":1,"maxLength":80},"puzzle":{"type":"string","pattern":"^[1-9.0-]{81}$"},"tags":{"default":[],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":30}}},"required":["name","puzzle"],"additionalProperties":false}}}},"responses":{"200":{"description":"Private library result.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"entry":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"puzzle":{"type":"string"},"solution":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991},"created":{"type":"number"},"updated":{"type":"number"}},"required":["id","name","puzzle","solution","tags","revision","created","updated"],"additionalProperties":false},"attribution":{"type":"object","properties":{"text":{"type":"string","const":"Created with Sudokumax"},"url":{"type":"string","const":"https://sudokumax.com"},"required":{"type":"boolean","const":true}},"required":["text","url","required"],"additionalProperties":{}}},"required":["entry","attribution"],"additionalProperties":false}}}},"400":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or disabled access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision conflict or library capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/library/delete":{"post":{"operationId":"library_delete","summary":"Delete a saved private puzzle by ID and current revision. Requires library:write. This permanently deletes the entry.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"revision":{"type":"integer","minimum":1,"maximum":9007199254740991}},"required":["id","revision"],"additionalProperties":false}}}},"responses":{"200":{"description":"Private library result.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"attribution":{"type":"object","properties":{"text":{"type":"string","const":"Created with Sudokumax"},"url":{"type":"string","const":"https://sudokumax.com"},"required":{"type":"boolean","const":true}},"required":["text","url","required"],"additionalProperties":{}}},"required":["deleted","id","attribution"],"additionalProperties":false}}}},"400":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or disabled access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Revision conflict or library capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"See error.code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/worksheets/{id}":{"get":{"operationId":"downloadWorksheet","summary":"Download a worksheet PDF","security":[{"bearerAuth":[]},{"downloadGrant":[]}],"parameters":[{"name":"options","in":"query","description":"JSON-encoded custom options from the returned pdfUrl. Do not alter signed download settings.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^(v1-[0-9]{81,1620}|c1-[a-f0-9]{32})$"}},{"name":"answers","in":"query","schema":{"enum":["0","1"],"default":"1"}},{"name":"paper","in":"query","schema":{"enum":["a4","letter"],"default":"a4"}}],"responses":{"200":{"description":"One, two or four puzzles per page according to options, followed by separate answer sheets when requested.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid, repeated or unknown query options"},"401":{"description":"Missing API key or download grant"},"403":{"description":"Revoked access or expired download grant"},"404":{"description":"Malformed collection identifier"},"405":{"description":"Unsupported method; inspect Allow"},"422":{"description":"One or more puzzles are not verified unique"},"429":{"description":"Rate limited; inspect Retry-After"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key generated at /developers. Keep it on your server."},"downloadGrant":{"type":"apiKey","in":"query","name":"download","description":"Short-lived PDF-only grant returned in pdfUrl; never an API key."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}