The ClubBattles API

Liveness probe

Checks the database as well as the process, and answers 503 with `status: degraded` when it cannot be reached. It did NOT probe the database before 21-09-2026, which made a Postgres outage invisible — a green `/health` while every viewer appeared signed out.

What commit this process is running

Read ONCE at process start, on purpose. The webapp reads the same file per request, so the two disagree for the whole of every deploy — a disagreement that persists after the deploy finishes is a build that never restarted the API.

This document

The OpenAPI 3.1 description of everything above. There is no checked-in `openapi.json` — this endpoint is the file.

Every title

The catalogue every other call needs, so it is reachable by ANY valid key regardless of scope, and anonymously. Listed titles only: sandbox titles and titles staff have hidden are left out, which is the one filter that takes a title off every list.

One title

Deliberately resolves sandbox and hidden titles, unlike the list above — otherwise their own subdomains would 404.

Club standings across every title

Derived, never stored: a club’s score is the sum over the titles it has a rated match in this season of (rating − 1000), with archived clubs and archived rosters excluded. Ties break on rated matches this season, then name.

One title’s ladder

Clubs with a rated match this season. Ratings reset to 1000 at every monthly UTC season boundary.

A club’s rating movements

Every entry `rating_history` holds for this club in this title. The ladder is rebuildable from this plus match results, which is why nothing but the rating module may write it.

Every club that exists

The apex directory. NOT a filter on the per-title list: a club that has retired from every title it entered still has an identity and appears here with no titles. Archived clubs are excluded from both.

Found a club

Makes you staff and puts you on no roster. A founder who wants to play adds themselves afterwards, which is also where the one-club-per-game seat is taken.

One club’s identity

Rename or re-tag a club

The slug deliberately does NOT move on rename — a rename that 404s every shared link is the worse bug.

Every title this club has entered

Includes titles the club has RETIRED from, which the club’s own `games` array excludes. That is the difference between the two and the reason this exists.

Archive or restore a club everywhere

Archive, never delete — rating history and match lineups reference a club forever. The route deliberately does not refuse an already-archived club, or archiving would be one-way and a mis-click permanent.

Merge another club into this one

Who administers this club

Running a club and playing for it are separate. Staff is club-wide and grants administration; membership is per game and grants play. Neither implies the other.

Add a staffer

Only the owner manages staff, so a staffer cannot lock the owner out.

Remove a staffer

The owner’s own staff row cannot be removed, because ownership transfer does not exist.

Clubs fielding a roster in this title

Found a club and enter it into this title

A club as it stands in one title

Rename or re-tag from inside a title

Two routes rename a club — this and the apex one. They agree today; a change to one is a change to half the product.

Retire or restore this title’s roster

Scoped to one title, unlike the apex archive route which archives the club everywhere.

A club’s roster in this title

Active members only. A player is on ONE club per game, enforced by a partial unique index rather than by a guard.

Add yourself to this roster

Where a founder takes their one-club-per-game seat. Refused if the roster is full or you already hold a seat in this title.

Leave, or remove a member

The roster lock binds BOTH sides: once a player has played a rated match this season, neither they nor staff may end that membership until the season changes or the club goes fourteen days without a rated match.

Enter this club into the title

Creates an empty roster, or restores one the club previously retired — with the members it was left with. 201 when the roster is new, 200 when it is restored.

A player’s profile in one title

Game-scoped because everything on it is — a rating is per game and so is a roster, so the same person has a different profile in a different title. Contact details are not in it.

Search players by name, tag or number

The autocomplete behind every field that takes a player. Signed-in rather than permissioned, because club staff need it. Returns the three fields a picker draws, all already printed on public pages — so it adds a way to LOOK somebody up, not a new fact about them.

Recent matches in a title

One match in full

Scores are ALWAYS club A then club B, never the reporter’s point of view — a bare "3-1" is what gets confirmed backwards, and a reversed confirmation is unrecoverable once rated.

Withdraw an unanswered result

DELETES the match, so the room reads "no result at all" and offers the report form again. Safe only because rating applies on entry to `completed`; never extend this to a rated match.

A club’s matches in a title

Report a result

The gate is enforced from the fixture found by the two club ids, never from a fixture id in the request, so it cannot be skipped by omitting a field.

Results awaiting this club’s answer

Confirm a reported result

Confirming is what enters `completed`, and entry to `completed` is what applies rating. The guard reads `match_results.reported_by` so the reporter cannot confirm their own result.

Dispute a reported result

Sends it to staff. A resolved dispute rates at resolution time, not retroactively at the original timestamp.

Whether the queue is open, and how many clubs are searching

Your club’s own queue state

Join the queue

Leave the queue

A club’s fixtures

One fixture

Lobby credentials are NOT in this response for a caller who is not in the match — they are generated at pairing for the two clubs playing.

Accept a proposed fixture

Decline a proposed fixture

Decline penalties are derived from the fixture row, never stored as a counter — and they are on the club, not on whoever happened to queue it in.

Match room chat

Polled, never socketed — the bearer token stays server-side and the process count is capped.

Post to the match room

The match room’s scoresheet

For a title with a scorer. Everything in it is replayed from the visits entered, so it cannot disagree with them. Room members only, like the chat.

Enter a visit

For the side whose throw it is. Send the darts — `throws`, one to three `{ ring, number? }` — or a total as `score`, with `darts` on a checkout. Darts are taken one at a time: past zero, leaving 1 on double-out, or reaching zero on anything but a double when the title is double-out, is a bust, and the visit ends on the dart that finished or went bust.

What a visit would do

The same checks entering it runs, and nothing written — so the room can ask a player to confirm what a visit scores, whether it goes bust or wins the leg, before it counts. With `edit: true`, what correcting the side’s last visit to this would do.

Save the darts picked so far

The visit being thrown, none to three darts, sent as the thrower taps them so the other side sees them land (the scoresheet’s `draft`). Only on your own throw — 409 otherwise, which only means the throw moved on. Not judged, and never a visit: entering one is still `POST …/visits`.

Correct your last visit

Replaces the most recent visit the caller’s side threw. If the other side has thrown since, the correction may not change whether the visit won the leg. Never once a result is filed.

Send the result from the scoresheet

Once a side has won and the report gate is open. Files the score, lineup and stats worked out from the visits; the other club then confirms or disputes it as usual.

Match camera signalling

The few messages two browsers swap to connect a camera — a hello, one offer, one answer, a bye. Video itself goes browser to browser and never reaches the API. Room members only, on a title with a camera; signals older than a minute are gone.

Send a camera signal

Make a phone camera link

A short-lived link a phone can open, with no sign-in, to stream the caller’s side’s board. The token is shown once and stored hashed.

What a phone camera link opens

The token is the credential. 404 once it has expired or its match is over.

Camera signalling, for a phone

Send a camera signal, as a phone

Always sent as a camera — the role is set by the link, not the request.

Create or refresh the caller’s account at sign-in

Guards itself rather than using the usual user guard, because it must answer BEFORE a users row exists. Not a general-purpose route — the webapp calls it once per sign-in.

Your own profile

Display name and avatar are read-only: `users/sync` overwrites them at every sign-in, so an editable name would be silently reverted.

Update your bio, timezone or notification preferences

A body carrying `displayName` is ignored rather than refused, for the reason above.

Clubs you play for or administer

Whether you may found a club

A ceiling on ACTIVE clubs one person may own. Archived clubs do not count towards it.

Claim a platform account

CLAIMED, never verified. Nothing checks a handle against Steam or Epic, and no reader may treat one as identity.

Drop a claimed platform account

Your API keys

Live keys first, then revoked ones. Revoked keys are shown rather than hidden, because "did I already revoke that" is a question this should answer.

Mint a key

THE ONLY TIME THE TOKEN IS EVER RETURNED. Nothing stores it and no later read can recover it — lose it and you mint a new key. Requires a signed-in session, which an API key cannot provide, so a key can never mint another key.

Revoke a key

Revoke, never delete: the row is the record that the credential existed, and its prefix stays claimed so a prefix in an old log always resolves to exactly one key. Takes effect on the next request — there is no cache in front of verification.

The board and the changelog

Everything planned, being built or shipped, with the date each thing shipped — the board and the changelog in one read. Ideas still under review and declined ones are NOT here, because they grow with the number of people suggesting rather than with the work: page through them at `/v1/roadmap/ideas`. Their counts are here so a page can show them without reading them. Hidden items are excluded. Personalised when a session is present — `viewerVoted` and `viewerIsAuthor` — and identical to a signed-out read otherwise, which is why any API key may call it.

One roadmap item

Withdraw your own idea

Only while nobody has answered it. It is deleted with its votes, so it stops counting towards your waiting ideas. Once answered it is part of the record, and this answers 409.

What people have suggested, a page at a time

Community ideas only. `top` and `new` are the ones still taking votes (under review, planned or being built) by votes or by age; `answered` is the ones that shipped or were declined, most recently answered first, with the reason in `reply`. Numbered pages: `top` can shift under a reader as votes move, which is what `new` is for. A page past the end answers an empty list with the real `total`, not a 404.

Suggest an idea

Posting an idea counts as your vote for it. At most 5 of your ideas may wait for an answer at once; past that this answers 409 with `error.code` `too_many_open_ideas`, and withdrawing one or getting an answer frees a slot. There is no time-based limit.

Find items like a title

Items still taking votes — under review, planned or being built — whose titles share words with `q`, best match first. Words are compared stemmed, with common words ignored; a longer `q` must share at least a third of its words. The suggestion form asks this while somebody types, so they vote for an existing idea instead of posting a copy.

Vote for an item

Idempotent: voting twice is one vote. Refused with 409 (`voting_closed`) once an item has shipped or been declined.

Take your vote back

Idempotent, and closed at the same point voting is.

Events in one month

Published events touching one UTC calendar month, in day order, for every title or — with `game` — for one — a multi-day event that starts before the month or runs past it is included. Seasons are not events and never appear here: a season is the UTC calendar month, so its start and end are the month itself.

One event