Skip to content

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 ​

methodpathpurposerate bucket
POST/gammonet/acquireworker: lease positions to analysenone (key required)
POST/gammonet/submitworker: return results for a leasenone (key required)
any/gammonet/statusanalysis queue and cache statisticsnone
any/healthzhealth and deploy checksnone
GET/api/leaderboardrated players by ratingread
GET/api/player/<pub>one player's rating card and recent matchesread
GET/api/fairnessaggregate dice histogram and chi-squareread
GET/api/puzzlea daily puzzle cardread
GET/api/puzzles/nexta puzzle from the pool, for a signed callerread (signature required)
POST/api/puzzles/<id>/attemptanswer a pool puzzlewrite (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-claimredeem a sign-in linkwrite
POST/api/cron/daily?key=<CRON_KEY>send today's puzzle mailwrite
GET/api/analysis/<matchId>analysis of a finished matchanalysis
GET/api/recordsids of the 50 most recent matchesread
GET/api/matchesthe 25 most recent matchesread
GET/records/<matchId>.jsondownload a signed recordread
GET/, /*static client from public/, and /src/* from the repositorynone

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 }. puzzle is the public view: position, dice, cube, score and number of choices, with no answers.
  • Over HTTP streak is always 0 and yours is always null: this route cannot tell who is asking, and public keys are public (/api/matches lists them), so it never reveals any player's scored answer. An authenticated client gets its own yours and streak from the WebSocket puzzle message.
  • Only today's puzzle is ever built on demand. A past date with no stored puzzle returns 404, and a future date also returns 404. 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 }. puzzle is the same public view as the daily: no answers. gap is how much better the best play is than the next one — the measure the pool sorts by. kind is checker.
  • 429 { error, allowance, upgrade } when the key has used its free answers for the day. allowance is { limit, used, remaining, resetAt }, and resetAt is midnight UTC.
  • 503 { error, seenEverything, retryAfterSeconds, allowance } when there is nothing to serve. seenEverything tells the two causes apart: false is a pool still being built, worth retrying in half a minute, and true is 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.

  • 200 with correct, rank, of, loss, best, alternatives, alreadyAnswered and stats.
  • 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 without hops, 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.

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", or 400 "that link has expired".
  • GET /email/unsubscribe?t=<token>: sets the subscription's daily flag to off. 200 "unsubscribed", or 400 "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, where ok and failed are counts, skipped is how many were not attempted because the batch aborted, and outcomes is a per-address true/false list
  • 500 { 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 ​

  • / serves public/index.html. Other paths are served from public/.

  • 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 under src/ is served: any other /src/ path returns 404.

  • Any path containing .. returns 400. A missing file returns 404.

  • 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 — is no-store. Other assets (images, fonts, the manifest) get public, max-age=86400.

  • A served .js has 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.js against today's server is a correctness problem rather than a stale pixel. Plain no-cache could not deliver that — the server sends no ETag, so "revalidate" never produced a 304, and a CDN in front of the origin rewrote no-cache into max-age=14400 (measured on the live site: origin no-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.png is the 512×512 picture for the domain's mailbox, rendered from public/mail-avatar.svg, and /bimi.svg is the same drawing inside the BIMI profile. Both are public, max-age=604800.

  • /privacy.html and /terms.html are the legal pages. Edit them to name yourself as the operator.

Rules engine, fairness protocol, verifier, analysis and worker: MIT. Server and client: AGPL-3.0-or-later.