{"openapi":"3.0.3","info":{"title":"Sudoku.best API","version":"1.0.0","description":"Human-logic Sudoku generate / solve / teach API. Difficulties are engine bands L1–L10. Cell indices are 0–80 row-major."},"servers":[{"url":"/"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"BoardInput":{"oneOf":[{"type":"string","pattern":"^[0-9]{81}$","description":"81 digits, 0=empty"},{"type":"array","items":{"type":["integer","null"],"minimum":0,"maximum":9},"minItems":81,"maxItems":81}]},"Difficulty":{"type":"string","enum":["L1","L2","L3","L4","L5","L6","L7","L8","L9","L10"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"paths":{"/health":{"get":{"security":[],"summary":"Health check","responses":{"200":{"description":"OK"}}}},"/v1/openapi.json":{"get":{"security":[],"summary":"OpenAPI document","responses":{"200":{"description":"OpenAPI 3 JSON"}}}},"/v1/techniques":{"get":{"summary":"Technique catalog","responses":{"200":{"description":"List of tactics"}}}},"/v1/generate":{"post":{"summary":"Generate a puzzle","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["difficulty"],"properties":{"difficulty":{"$ref":"#/components/schemas/Difficulty"},"seed":{"type":"integer"},"timeoutMs":{"type":"integer"},"maxAttempts":{"type":"integer"}}}}}},"responses":{"200":{"description":"Puzzle + solution + analysis"}}}},"/v1/solve":{"post":{"summary":"Solve (board + analysis, no steps)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["board"],"properties":{"board":{"$ref":"#/components/schemas/BoardInput"}}}}}},"responses":{"200":{"description":"Solved board"}}}},"/v1/solve/summary":{"post":{"summary":"Solve with compact step list","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["board"],"properties":{"board":{"$ref":"#/components/schemas/BoardInput"}}}}}},"responses":{"200":{"description":"Summary steps"}}}},"/v1/solve/detailed":{"post":{"summary":"Solve with cause→effect steps","description":"Each step lists pattern cell candidates (causes) and eliminations/placements/adds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["board"],"properties":{"board":{"$ref":"#/components/schemas/BoardInput"}}}}}},"responses":{"200":{"description":"Detailed steps"}}}},"/v1/analyze":{"post":{"summary":"Rate / analyze a board","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["board"],"properties":{"board":{"$ref":"#/components/schemas/BoardInput"}}}}}},"responses":{"200":{"description":"Analysis"}}}},"/v1/hint":{"post":{"summary":"Single next human-logic step","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["board"],"properties":{"board":{"$ref":"#/components/schemas/BoardInput"}}}}}},"responses":{"200":{"description":"Hint"}}}},"/v1/validate":{"post":{"summary":"Validate format, conflicts, uniqueness","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["board"],"properties":{"board":{"$ref":"#/components/schemas/BoardInput"}}}}}},"responses":{"200":{"description":"Validation result"}}}},"/v1/teach":{"post":{"summary":"Teaching hint (premium)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["board"],"properties":{"board":{"$ref":"#/components/schemas/BoardInput"},"notes":{"type":"array","items":{"type":"array","items":{"type":"integer"}}}}}}}},"responses":{"200":{"description":"Teaching hint"},"403":{"description":"Premium required"}}}},"/v1/teach/continue":{"post":{"summary":"Apply teach step and get next (premium)","responses":{"200":{"description":"Next teaching hint"},"403":{"description":"Premium"}}}},"/v1/candidates":{"post":{"summary":"Legal candidates per cell (premium)","responses":{"200":{"description":"Candidates"},"403":{"description":"Premium"}}}},"/v1/techniques/example":{"post":{"summary":"Generate illustrated technique example (premium)","responses":{"200":{"description":"Examples"},"403":{"description":"Premium"}}}},"/v1/generate/batch":{"post":{"summary":"Batch generate puzzles (premium)","responses":{"200":{"description":"Puzzles"},"403":{"description":"Premium"}}}}}}