{"openapi":"3.1.0","info":{"title":"Sudokumax Puzzle API","version":"1.0.0","description":"Generate verified Sudoku worksheets, downloadable PDFs and self-contained playable 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. 60 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. Beginner puzzles are verified singles-solvable; other generator labels are not calibrated human difficulty ratings. Developer accounts manage access; published puzzle links are public.","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"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success. A check may return unknown when its search budget is exhausted.","content":{"application/json":{"schema":{"type":"object","properties":{"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":"singles-v1"},"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","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":"Puzzle is not verified unique","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":{"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"},"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","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":"Puzzle is not verified unique","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":{"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":"singles-v1"},"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","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":"Puzzle is not verified unique","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":{"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},"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","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":"Puzzle is not verified unique","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 singles 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}$"}},"required":["puzzle","progress"],"additionalProperties":false}}}},"responses":{"200":{"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},"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}},"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},"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","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","changedGivens","incorrectCells","conflictCells","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":"Puzzle is not verified unique","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":{"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":"Puzzle is not verified unique","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"]}},"required":["puzzles"],"additionalProperties":false}}}},"responses":{"200":{"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"]}},"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":"Puzzle is not verified unique","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"]},"includeAnswers":{"default":true,"type":"boolean"},"paper":{"default":"a4","type":"string","enum":["a4","letter"]}},"additionalProperties":false},"example":{"count":20,"difficulty":"beginner","includeAnswers":true,"paper":"a4"}}}},"responses":{"200":{"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":"singles-v1"},"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","techniques","solvedWithSupportedTechniques","remainingCells","explanation"]},"id":{"type":"string"},"playableUrl":{"type":"string","format":"uri"}},"required":["attribution","puzzle","solution","requestedDifficulty","analysis","id","playableUrl"]}},"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":"Puzzle is not verified unique","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/{id}":{"get":{"operationId":"downloadWorksheet","summary":"Download a worksheet PDF","security":[{"bearerAuth":[]},{"downloadGrant":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^v1-[0-9]{81,1620}$"}},{"name":"answers","in":"query","schema":{"enum":["0","1"],"default":"1"}},{"name":"paper","in":"query","schema":{"enum":["a4","letter"],"default":"a4"}}],"responses":{"200":{"description":"One puzzle per page, 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"}}}}}}}}}}}