Appearance
HTTP API
Every route in src/server/index.js, in the order the server matches them. Most routes do not check the HTTP method, so "GET" below means "the method the client uses". Rate-limit buckets depend on method and path: see Rate limiting.
JSON responses carry cache-control: no-store and the security headers, unless stated otherwise.
Summary
| method | path | purpose | rate bucket |
|---|---|---|---|
| POST | /gammonet/acquire | worker: lease positions to analyse | none (key required) |
| POST | /gammonet/submit | worker: return results for a lease | none (key required) |
| any | /gammonet/status | analysis queue and cache statistics | none |
| any | /healthz | health and deploy checks | none |
| GET | /api/leaderboard | rated players by rating | read |
| GET | /api/player/<pub> | one player's rating card and recent matches | read |
| GET | /api/fairness | aggregate dice histogram and chi-square | read |
| GET | /api/puzzle | a daily puzzle card | read |
| GET | /api/puzzles/next | a puzzle from the pool, for a signed caller | read (signature required) |
| POST | /api/puzzles/<id>/attempt | answer a pool puzzle | write (signature required) |
| GET | /email/verify?t=<token> | confirm a puzzle subscription (HTML page) | none |
| GET | /email/unsubscribe?t=<token> | stop the daily puzzle mail (HTML page) | none |
| POST | /api/login-claim | redeem a sign-in link | write |
| POST | /api/cron/daily?key=<CRON_KEY> | send today's puzzle mail | write |
| GET | /api/analysis/<matchId> | analysis of a finished match | analysis |
| GET | /api/records | ids of the 50 most recent matches | read |
| GET | /api/matches | the 25 most recent matches | read |
| GET | /records/<matchId>.json | download a signed record | read |
| GET | /, /* | static client from public/, and /src/* from the repository | none |
Worker endpoints
POST /gammonet/acquire
Header x-gammonet-key: <GAMMONET_KEY>. Body { engineId, count, workerId }. count defaults to 8, maximum 64.
json
{ "token": "…uuid…", "jobs": [{ "key": "…", "req": { "pos": {}, "onRoll": 0, "dice": [3, 1], "cube": {}, "score": [0, 0], "matchLength": 0, "crawford": false }, "ply": 2, "engineId": "gnubg-1.07" }] }{ "jobs": [] } means there is no work for that engine.
POST /gammonet/submit
Header x-gammonet-key. Body { token, results: [{ key, result }], workerId }. The response is { ok: true, accepted, ignored? } or { ok: false, error } (unknown token, that token belongs to another worker). Results for positions not in the lease are ignored and counted as rejected. See Analysis & PR for the checks.
Both worker endpoints answer 503 { error: 'this instance accepts no volunteer workers' } when GAMMONET_KEY is unset, and 401 for a wrong or missing key.
/gammonet/status
No key required. Returns { depth, queued, served, dropped, rejected, cache: { …, hitRate }, annotations: { hits, misses, coalesced, hitRate } }.
Health
/healthz
{ ok, uptime, online, matches, rssMB, heapMB, botEngine, dice, serverKey, queue, errors, backup, limiterKeys }. See Monitoring for what each field means.
Players and ratings
GET /api/leaderboard
Query: minGames (default 3) and limit (default 50, maximum 200). Returns { players: [{ pub, name, games, wins, rating, rd, provisional, conservative }], system }. In this response pub is shortened to its first 16 hex characters.
GET /api/player/<pub>
The full 64-hex public key. Returns { rating, rd, provisional, conservative, name, games, wins, matches }, where matches holds the player's 25 most recent rows from the match index. Returns 404 { error: 'no such player' } for an unknown key.
Dice
GET /api/fairness
json
{
"protocol": "hmac-sha256/hashchain-reveal-v2",
"rolls": 0,
"counts": { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0, "6": 0 },
"chi2": 0, "df": 5, "critical95": 11.07,
"uniform": null,
"note": "…this histogram is a sanity check, not the proof…"
}uniform stays null until at least 600 dice have been counted. After that it is chi2 < 11.07. Counts are added when a match finishes.
Puzzle
GET /api/puzzle
Query: date (YYYY-MM-DD, defaults to today in UTC). A pub parameter is ignored.
- Returns
{ puzzle, stats: { tries, solved }, streak, yours }.puzzleis the public view: position, dice, cube, score and number of choices, with no answers. - Over HTTP
streakis always0andyoursis alwaysnull: this route cannot tell who is asking, and public keys are public (/api/matcheslists them), so it never reveals any player's scored answer. An authenticated client gets its ownyoursandstreakfrom the WebSocketpuzzlemessage. - Only today's puzzle is ever built on demand. A past date with no stored puzzle returns
404, and a future date also returns404. Otherwise one unauthenticated request per past date could queue many multi-second builds in parallel and freeze every live match. - If a build fails, the response is
503 { error }.
Answers are submitted over the WebSocket (puzzle-attempt), because that connection has already proved its key.
The puzzle pool
The daily puzzle is one position a day, the same for everybody. A tool that is not a browser needs a different thing: a fresh position every few minutes, answered immediately, dozens in an afternoon. That is what these two routes serve, and they are what the Claude Code plugin talks to.
Both require a signature. An unauthenticated feed of puzzles is an unauthenticated feed of engine time, and the daily allowance has to be counted against somebody.
Signing a request
Authorization: Gammonchain <publicKeyHex>.<unixSeconds>.<signatureHex>The signature is Ed25519 over sha256(signingString), where the signing string is four lines:
<METHOD>
<path>
<unixSeconds>
<sha256 of the request body, hex; sha256 of "" for a GET>path is the path alone — no query string and no origin. The body hash covers the exact bytes sent, so a client that serialises its JSON twice will sign one thing and send another.
This is deliberately not a bearer token. There is no secret on the server, nothing to rotate, and a captured header authorises exactly the one request it was made for. Requests are refused if the caller's clock is more than 300 seconds from the server's, and the error says so in those words, because the fix is on the caller's machine.
The reference implementation of both halves is src/server/plugin-auth.js. test/plugin-auth.js signs with the plugin's own vendored copy and verifies with the server's, so the two cannot drift apart silently.
GET /api/puzzles/next
The sharpest position this key has not been served before — not merely one it has not answered. A client that prefetches the next position while you are still looking at the current one has answered nothing yet, so excluding only answered positions hands it the same row every time.
Being served a position therefore counts, whether or not it is answered. A client that fetches one and then crashes loses it, which is a far smaller problem than a client whose shelf fills up with one puzzle.
200 { id, kind, puzzle, gap, allowance, stats }.puzzleis the same public view as the daily: no answers.gapis how much better the best play is than the next one — the measure the pool sorts by.kindischecker.429 { error, allowance, upgrade }when the key has used its free answers for the day.allowanceis{ limit, used, remaining, resetAt }, andresetAtis midnight UTC.503 { error, seenEverything, retryAfterSeconds, allowance }when there is nothing to serve.seenEverythingtells the two causes apart:falseis a pool still being built, worth retrying in half a minute, andtrueis a key that has played everything in the pool, which is not worth retrying until more matches have been recorded. The allowance rides along either way, so a client never has to guess at its own standing while the shelf is being restocked.
No two rows in the pool are the same position. The generator ranks candidates by how sharp they are, so without a uniqueness rule it converges on whichever position in the corpus is sharpest and stores it again under a new id; the pool is keyed on the position itself — board, dice, score, match length, cube and Crawford — and a build that lands on one already held is discarded. When every candidate is already in the pool, the filler stops rather than grinding the engine to rediscover them.
Serving a puzzle also kicks the background filler, which tops the pool up to POOL_TARGET (40 by default) one position at a time and only while no match is being played — the box that generates these is the box people are playing on. A timer does the same every minute, so a freshly deployed server stocks itself instead of making the first caller poke it.
POST /api/puzzles/<id>/attempt
Body { hops: [{ from, to }] }, where 24 is the bar and 25 is off, as everywhere else in the protocol.
200withcorrect,rank,of,loss,best,alternatives,alreadyAnsweredandstats.- Matching is by resulting position, not hop order: there are several ways to write the same play and nobody should be marked wrong for moving the same checkers in a different sequence.
- The first answer stands. Submitting again returns the same verdict with
alreadyAnswered: true, which is what makes a client's offline queue safe to replay. 400 { error }for a play that is not legal, a body withouthops, or an id the server does not know.
Free allowance
POOL_FREE_PER_DAY answers per key per day, 30 by default, counted on attempts rather than on positions served — so skipping a position you do not fancy costs nothing.
Email links
Both routes return a small standalone HTML page, since they are opened from a mail client.
GET /email/verify?t=<token>: confirms a pending subscription.200"you are subscribed", or400"that link has expired".GET /email/unsubscribe?t=<token>: sets the subscription's daily flag to off.200"unsubscribed", or400"nothing to unsubscribe". Rating and match history are not affected.
Accounts
POST /api/login-claim
Body { token }. The token is consumed on first use, and it expires 30 minutes after it was issued.
json
{ "pub": "…", "username": "…", "email": "…", "jwk": { "kty": "OKP", "crv": "Ed25519", "…": "…" } }jwk is the account's private key, which the browser installs. An unknown, used or expired token returns 400 { error: 'that link has expired — ask for a new one' }.
Cron
POST /api/cron/daily?key=<CRON_KEY>
Sends today's puzzle to every due subscriber, up to MAIL_DAILY_CAP. Safe to call repeatedly. Returns 403 { error: 'bad key' } if CRON_KEY is unset or does not match. Response shapes:
{ skipped: 'mail provider not configured' }{ sent: 0, due: 0 }when nobody is due{ date, ok, failed, skipped, outcomes, due }after a send, whereokandfailedare counts,skippedis how many were not attempted because the batch aborted, andoutcomesis a per-address true/false list500 { error }on failure
Matches and records
GET /api/analysis/<matchId>
Query: deep=1 for engine analysis by a worker. Otherwise the server's built-in heuristic is used. Returns 404 for an unknown match. Otherwise the response is { matchId, engineId, ply, players, result, totals, moves, provisional, scoredIn, prNote }, computed once per match and tier. When deep analysis cannot complete, the response is 503 { error, hint: 'no gammonet worker is connected for deep analysis' }. See Analysis & PR.
GET /api/records
An array of the 50 most recent match ids, newest first, read from the SQLite index.
GET /api/matches
The 25 most recent rows of the match index: id, created, length, p0, p1 (full public keys), name0, name1, score0, score1, winner, rated, reason, ratings before and after for both players, and final_hash.
GET /records/<matchId>.json
The full signed record as JSON (the server decompresses it), with content-disposition: attachment. The .json suffix is optional. An unknown id falls through to the static handler and returns 404 not found. This response does not carry the security headers or a cache-control header.
Static files
/servespublic/index.html. Other paths are served frompublic/.Paths under
/src/core/and/src/verify/are served from the repository root. This is how the browser imports the same modules the server runs, so a match is checked by exactly the server's own rules and dice code. Nothing else undersrc/is served: any other/src/path returns404.Any path containing
..returns400. A missing file returns404.Every page names its code with a build stamp:
app.js?v=9df28fd1b8. The stamp is derived from the size and modification time of every file that can be served as code (public/,src/core/,src/verify/), so it changes when a deploy changes something and not otherwise.A request carrying the current stamp is served
public, max-age=31536000, immutable— that URL can only ever mean that content.Everything else — an old stamp, no stamp, any
.html, and/sw.js— isno-store. Other assets (images, fonts, the manifest) getpublic, max-age=86400.A served
.jshas the same stamp appended to its own relative imports, so the whole module graph moves together rather than half of it.Why it works this way: the client speaks a versioned protocol to one server, so a browser running yesterday's
app.jsagainst today's server is a correctness problem rather than a stale pixel. Plainno-cachecould not deliver that — the server sends noETag, so "revalidate" never produced a 304, and a CDN in front of the origin rewroteno-cacheintomax-age=14400(measured on the live site: originno-cache, edge four hours). A URL that changes with the content sidesteps every cache in the path, including one with its own opinions, and lets the files be cached properly instead of re-downloaded on every visit./mail-avatar.pngis the 512×512 picture for the domain's mailbox, rendered frompublic/mail-avatar.svg, and/bimi.svgis the same drawing inside the BIMI profile. Both arepublic, max-age=604800./privacy.htmland/terms.htmlare the legal pages. Edit them to name yourself as the operator.