{"openapi":"3.1.0","info":{"title":"Aback Chess public API","version":"1.0.0","summary":"Read-only public answers: the site's totals and the puzzle of the day.","description":"No key and no account. Every answer is the same for everyone and is cached at the edge, so poll politely: the totals change every few minutes and the daily puzzle once a UTC day.\n\nResponses use one envelope: {\"ok\": true, \"data\": ...} or {\"ok\": false, \"error\": {\"code\", \"message\", \"hint\", \"docs\"}}. `code` is one of NOT_FOUND, NO_PUZZLE, RATE_LIMITED, UNKNOWN_ERROR, DATABASE_UNAVAILABLE.\n\nRate limit: about 120 requests a minute from one address. Every answer carries the RateLimit and RateLimit-Policy headers (and RateLimit-Limit, -Remaining, -Reset); a 429 adds Retry-After.\n\nVersioning: this is version 1, at /api/v1/. Every answer says so in its API-Version header. A breaking change gets a new path (/api/v2/); the old version keeps answering for at least six months after the new one ships, and its answers carry Deprecation and Sunset headers (RFC 9745, RFC 8594) for that time. The unversioned paths /api/stats and /api/puzzles/daily answer as version 1.","contact":{"name":"Aback Chess support","url":"https://abackchess.com/contact","email":"support@abackchess.com"},"termsOfService":"https://abackchess.com/terms","x-api-versioning":{"scheme":"url-path","current":"v1","header":"API-Version","deprecation":["Deprecation","Sunset"],"minimumNoticeDays":180,"policy":"https://abackchess.com/developers#versioning-and-deprecation"},"x-deprecation-policy":"https://abackchess.com/developers#versioning-and-deprecation"},"externalDocs":{"description":"Developers: the API, the MCP servers and agent access","url":"https://abackchess.com/developers"},"servers":[{"url":"https://abackchess.com","description":"Production"}],"paths":{"/api/v1/stats":{"get":{"operationId":"getSiteTotals","summary":"Site totals","description":"Players signed up, games reviewed, puzzles solved and games played against the computer, all time. Use it to quote how much the site is used.","tags":["site"],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"The totals.","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"API-Version":{"$ref":"#/components/headers/ApiVersion"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"},"Link":{"$ref":"#/components/headers/DeprecationLink"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTotalsResponse"}}}},"429":{"description":"Too many requests from this address. Wait Retry-After seconds.","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"API-Version":{"$ref":"#/components/headers/ApiVersion"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"},"Link":{"$ref":"#/components/headers/DeprecationLink"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something went wrong on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/puzzles/daily":{"get":{"operationId":"getDailyPuzzle","summary":"Puzzle of the day","description":"The same puzzle for everyone for the UTC day, from the Lichess puzzle database (CC0). `moves` is in UCI: the first move is the opponent's, played to reach the position the solver faces; the rest is the solution. Do not reveal the solution to someone who wants to solve it.","tags":["puzzles"],"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"description":"Today's puzzle.","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"API-Version":{"$ref":"#/components/headers/ApiVersion"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"},"Link":{"$ref":"#/components/headers/DeprecationLink"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyPuzzleResponse"}}}},"404":{"description":"No puzzle has been set for today (code NO_PUZZLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests from this address. Wait Retry-After seconds.","headers":{"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"API-Version":{"$ref":"#/components/headers/ApiVersion"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"},"Link":{"$ref":"#/components/headers/DeprecationLink"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something went wrong on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"parameters":{"ApiVersion":{"name":"API-Version","in":"header","required":false,"description":"The API version the client was written for. Optional: the path names the version; the answer's API-Version header confirms it.","schema":{"type":"string","enum":["1"],"default":"1"}}},"headers":{"ApiVersion":{"description":"The API version that answered.","schema":{"type":"string","example":"1"}},"RateLimit":{"description":"Remaining requests and seconds to the reset, as in the IETF RateLimit fields: \"public\";r=119;t=60.","schema":{"type":"string"}},"RateLimitPolicy":{"description":"The policy: \"public\";q=120;w=60.","schema":{"type":"string"}},"RateLimitLimit":{"description":"Requests allowed in the window.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests left in the window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the window resets.","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}},"Deprecation":{"description":"Sent only once this version is deprecated (RFC 9745): when it was deprecated, as @<unix seconds>. Absent while the version is current.","schema":{"type":"string","example":"@1798761600"}},"Sunset":{"description":"Sent with Deprecation (RFC 8594): the HTTP date after which this version stops answering, at least six months after the deprecation.","schema":{"type":"string","example":"Thu, 01 Jul 2027 00:00:00 GMT"}},"DeprecationLink":{"description":"Sent with Deprecation: rel=\"deprecation\" pointing at the versioning policy, and rel=\"successor-version\" at the new version.","schema":{"type":"string"}}},"schemas":{"Error":{"type":"object","description":"Every failure, in the same envelope.","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["NOT_FOUND","NO_PUZZLE","RATE_LIMITED","UNKNOWN_ERROR","DATABASE_UNAVAILABLE"],"description":"Machine-readable; branch on this."},"message":{"type":"string","description":"What went wrong, for a person."},"hint":{"type":"string","description":"What to do about it."},"docs":{"type":"string","format":"uri","description":"Where the API is documented."}}}}},"SiteTotals":{"type":"object","required":["players","reviews","puzzles","games"],"properties":{"players":{"type":"integer","minimum":0,"description":"Accounts made on the site."},"reviews":{"type":"integer","minimum":0,"description":"Games reviewed."},"puzzles":{"type":"integer","minimum":0,"description":"Puzzles solved."},"games":{"type":"integer","minimum":0,"description":"Games played against the computer opponents."}}},"Puzzle":{"type":"object","required":["id","fen","moves","rating","ratingDeviation","popularity","themes"],"properties":{"id":{"type":"string","description":"The Lichess puzzle id."},"fen":{"type":"string","description":"The position before the opponent's first move."},"moves":{"type":"array","items":{"type":"string","pattern":"^[a-h][1-8][a-h][1-8][qrbn]?$"},"description":"UCI moves: the opponent's move, then the solution."},"rating":{"type":"integer"},"ratingDeviation":{"type":"integer"},"popularity":{"type":"integer"},"themes":{"type":"array","items":{"type":"string"}},"opening":{"type":"string"}}},"DailyPuzzle":{"type":"object","required":["day","puzzle"],"properties":{"day":{"type":"string","format":"date","description":"The UTC day, YYYY-MM-DD."},"puzzle":{"$ref":"#/components/schemas/Puzzle"}}},"SiteTotalsResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/SiteTotals"}},"additionalProperties":false},"DailyPuzzleResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/DailyPuzzle"}},"additionalProperties":false}}}}