Skip to content

Leaderboard api #561

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
btfcookies wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Leaderboard api #561

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3af0fa2
feat: add a public /api/leaderboard endpoint
btfcookies Aug 7, 2026
6dae740
feat: gate /api/leaderboard behind a shared secret
btfcookies Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions client/tools/api-docs/bonus.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/check-answer.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer" class="active fw-semibold" aria-current="page"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/frequency-list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
12 changes: 12 additions & 0 deletions client/tools/api-docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down Expand Up @@ -152,6 +154,16 @@ <h5 class="mt-4 md-2">Question Stats</h5>
</li>
</ul>

<h5 class="mt-4 md-2">Leaderboard</h5>
<ul class="list-group list-group-flush">
<li class="list-group-item">
<a href="./leaderboard">
<div><code>GET</code> <code>/leaderboard</code></div>
</a>
<div>Rank every user by the number of questions they have heard. Requires a key.</div>
</li>
</ul>

<h5 class="mt-4 md-2">Other</h5>
<ul class="list-group list-group-flush">
<li class="list-group-item">
Expand Down
174 changes: 174 additions & 0 deletions client/tools/api-docs/leaderboard.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
<!doctype html>
<html lang="en">

<head>
<title>QBReader - API Docs - Leaderboard</title>
<!--#include virtual="/ssi/head.html" -->
<meta name="description" content="The API documentation for QB Reader.">
</head>

<body>
<!--#include virtual="/ssi/nav.html" -->

<div class="container-xl mt-3 mb-4 row">
<div class="col-md-1"></div> <!-- empty column for some left margin -->
<!-- docs sidebar -->
<div class="d-none d-md-block col-2 h-100" id="docsSidebar">
<h4 class="offcanvas-title" id="docsSidebarLabel">API Reference</h4>
<div class="navbar-nav me-auto mb-2 mb-lg-0">
<a href="."><code>Overview</code></a>
<a href="./schemas"><code>Object Schemas</code></a>
<h5 class="mt-4 mb-2">Database</h5>
<a href="./query"><code>query</code></a>
<a href="./random-bonus"><code>random-bonus</code></a>
<a href="./random-tossup"><code>random-tossup</code></a>
<a href="./packet"><code>packet</code></a>
<a href="./num-packets"><code>num-packets</code></a>
<a href="./set-list"><code>set-list</code></a>
<a href="./bonus"><code>bonus</code></a>
<a href="./tossup"><code>tossup</code></a>
<a href="./frequency-list"><code>frequency-list</code></a>
<h5 class="mt-4 mb-2">Multiplayer</h5>
<a href="./multiplayer/room-list"><code>room-list</code></a>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard" class="active fw-semibold" aria-current="page"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
<a href="./report-question"><code>report-question</code></a>
</div>
</div>

<div class="col-12 col-md-9">
<h3 class="md-4">
<div><code>GET</code> <code>qbreader.org/api/leaderboard</code></div>
</h3>

<p>
Rank every user by the number of questions they have heard.
Results are recomputed at most once every five minutes.
</p>

<div class="alert alert-warning">
<strong>This endpoint is not open.</strong> It returns every user's
username alongside their play stats, so it requires a key. Contact
a maintainer for access; unauthorized requests receive
<code>401</code>.
</div>

<a href="#parameters" class="text-body">
<h4 class="mt-4 md-2" id="parameters">Parameters</h4>
</a>
<ul class="list-group list-group-flush">
<li class="list-group-item">
<div>
<code>key</code><code class="text-muted">: string</code>
<span class="text-muted">Required</span>
</div>
<div>
The access key you were given. Requests with a missing or
incorrect key receive <code>401</code>.
</div>
</li>
<li class="list-group-item">
<div>
<code>limit</code><code class="text-muted">: number</code>
<span class="text-muted">Optional</span>
</div>
<div>
The maximum number of users to return.
Defaults to <code>50</code>, and is clamped to the range 1&ndash;500.
</div>
</li>
<li class="list-group-item">
<div>
<code>minQuestions</code><code class="text-muted">: number</code>
<span class="text-muted">Optional</span>
</div>
<div>
Exclude users who have heard fewer than this many questions.
Defaults to <code>0</code>. Applied before <code>limit</code>.
</div>
</li>
</ul>

<a href="#returns" class="text-body">
<h4 class="mt-4 md-2" id="returns">Returns</h4>
</a>
<div>
A JSON <code>object</code> with the following properties:
</div>
<ul class="list-group list-group-flush">
<li class="list-group-item">
<div>
<code>leaderboard</code><code class="text-muted">: Object[]</code>
</div>
<div>
<p>
An array of <code>objects</code>, sorted from most to least questions heard.
Users who have been deleted are omitted.
</p>
<pre class="bg-dark p-3 rounded"><code class="text-light">{
_id: string // the user's id
username: string
tossupCount: number // tossups heard
bonusCount: number // bonuses heard
total: number // tossupCount + bonusCount
numCorrect: number // tossups answered correctly
powers: number // tossups buzzed for 15 or more
tens: number // tossups buzzed for exactly 10
negs: number // tossups buzzed for a negative value
tossupPoints: number
bonusPoints: number
points: number // tossupPoints + bonusPoints
pptu: number // points per tossup heard
ppb: number // points per bonus heard
accuracy: number // numCorrect / tossupCount, from 0 to 1
averageCorrectCelerity: number // from 0 to 1; higher means an earlier buzz
}</code></pre>
</div>
</li>
<li class="list-group-item">
<div>
<code>count</code><code class="text-muted">: number</code>
</div>
<div>
The number of users in <code>leaderboard</code>.
</div>
</li>
<li class="list-group-item">
<div>
<code>generatedAt</code><code class="text-muted">: string</code>
</div>
<div>
An ISO 8601 timestamp for when these rankings were computed.
</div>
</li>
</ul>

<a href="#errors" class="text-body">
<h4 class="mt-4 md-2" id="errors">Errors</h4>
</a>
<ul class="list-group list-group-flush">
<li class="list-group-item">
<code>401</code>
<div>The <code>key</code> parameter is missing or incorrect.</div>
</li>
<li class="list-group-item">
<code>503</code>
<div>
The rankings could not be computed. Returns a JSON
<code>object</code> containing an <code>error</code> string.
</div>
</li>
</ul>
</div>
</div>


</body>

</html>
2 changes: 2 additions & 0 deletions client/tools/api-docs/multiplayer/room-list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="../question-stats/bonus"><code>bonus</code></a>
<a href="../question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="../leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="../check-answer"><code>check-answer</code></a>
<a href="../random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/num-packets.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/packet.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/query.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/question-stats/bonus.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="../question-stats/bonus" class="active fw-semibold" aria-current="page"><code>bonus</code></a>
<a href="../question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="../leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="../check-answer"><code>check-answer</code></a>
<a href="../random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/question-stats/tossup.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="../question-stats/bonus"><code>bonus</code></a>
<a href="../question-stats/tossup" class="active fw-semibold" aria-current="page"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="../leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="../check-answer"><code>check-answer</code></a>
<a href="../random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/random-bonus.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/random-name.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name" class="active fw-semibold" aria-current="page"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/random-tossup.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/report-question.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/schemas/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="../question-stats/bonus"><code>bonus</code></a>
<a href="../question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="../leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="../check-answer"><code>check-answer</code></a>
<a href="../random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/set-list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
2 changes: 2 additions & 0 deletions client/tools/api-docs/tossup.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ <h5 class="mt-4 mb-2">Multiplayer</h5>
<h5 class="mt-4 mb-2">Question Stats</h5>
<a href="./question-stats/bonus"><code>bonus</code></a>
<a href="./question-stats/tossup"><code>tossup</code></a>
<h5 class="mt-4 mb-2">Leaderboard</h5>
<a href="./leaderboard"><code>leaderboard</code></a>
<h5 class="mt-4 mb-2">Other</h5>
<a href="./check-answer"><code>check-answer</code></a>
<a href="./random-name"><code>random-name</code></a>
Expand Down
Loading
Loading