# Aback Chess public API (version 1)

Two read-only answers, free to use with no key and no account. Both are the same for everyone and cached at the edge. The full guide, with the MCP servers and agent access, is https://abackchess.com/developers.

- OpenAPI description: https://abackchess.com/openapi.json
- API catalog: https://abackchess.com/.well-known/api-catalog
- API root: https://abackchess.com/api

## Conventions

Every response uses one envelope:

```json
{ "ok": true, "data": { } }
{ "ok": false, "error": { "code": "NO_PUZZLE", "message": "There is no daily puzzle yet.", "hint": "...", "docs": "https://abackchess.com/developers" } }
```

Error codes: `NOT_FOUND` (no such endpoint, 404), `NO_PUZZLE` (404), `RATE_LIMITED` (429), `UNKNOWN_ERROR` (500), `DATABASE_UNAVAILABLE` (503). Branch on `code`, show `message`.

**Rate limit.** About 120 requests a minute from one address. Every answer carries `RateLimit` and `RateLimit-Policy` (the IETF fields) and `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`. A 429 adds `Retry-After` in seconds.

**Versioning.** This is version 1, at `/api/v1/`, and every answer says so in its `API-Version` header. A breaking change gets a new path; the old version keeps answering for at least six months after, with `Deprecation` and `Sunset` headers (RFC 9745, RFC 8594) on its answers. No version has been deprecated yet. The policy: https://abackchess.com/developers#versioning-and-deprecation. `/api/stats` and `/api/puzzles/daily` answer as version 1.

## GET /api/v1/stats

The site's totals, all time: `players` (accounts), `reviews` (games reviewed), `puzzles` (puzzles solved) and `games` (games against the computer opponents). Refreshed every few minutes.

```
curl https://abackchess.com/api/v1/stats
```

## GET /api/v1/puzzles/daily

The puzzle of the day for the current UTC day: `day`, and `puzzle` with `id`, `fen`, `moves` (UCI; the first is the opponent's move that sets up the puzzle, the rest is the solution), `rating`, `ratingDeviation`, `popularity`, `themes` and, when known, `opening`. Puzzles come from the Lichess puzzle database (CC0). Returns 404 with `NO_PUZZLE` if none is set.

```
curl https://abackchess.com/api/v1/puzzles/daily
```

## MCP server

For agents, the same answers and more chess tools are available over MCP at https://abackchess.com/mcp (Streamable HTTP, no key, read-only). Its server card is https://abackchess.com/.well-known/mcp/server-card.json. A player's own games and progress are at https://abackchess.com/mcp/account, behind OAuth 2.1 with self-serve client registration, or registration by email as https://abackchess.com/auth.md describes.

## What is not offered

Game analysis runs in the visitor's browser, on their own device, so there is no analysis API. To have a game reviewed, link the visitor to the review with the game in the address, as the agent skill describes: https://abackchess.com/.well-known/agent-skills/aback-chess/SKILL.md
