From c2c8e188248311baf9f073c866a9d108b7da3f31 Mon Sep 17 00:00:00 2001
From: johndoknjas <jdoknjas@sfu.ca>
Date: Sun, 26 Apr 2026 22:16:34 -0700
Subject: [PATCH 1/4] Update documentation to include the new `page` query
 param.

---
 doc/specs/tags/users/api-player-top-nb-perfType.yaml | 10 ++++++++++
 scripts/update-examples/users.ts                     |  3 +++
 2 files changed, 13 insertions(+)

diff --git a/doc/specs/tags/users/api-player-top-nb-perfType.yaml b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
index 0c24a696..7a5d3888 100644
--- a/doc/specs/tags/users/api-player-top-nb-perfType.yaml
+++ b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
@@ -39,6 +39,16 @@ get:
           - racingKings
           - threeCheck
       required: true
+    - in: query
+      name: page
+      description: Leaderboard page number
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 20
+        default: 1
+        example: 1
+      required: false
   responses:
     "200":
       description: The list of top players for the variant.
diff --git a/scripts/update-examples/users.ts b/scripts/update-examples/users.ts
index f465f437..cbef5da7 100644
--- a/scripts/update-examples/users.ts
+++ b/scripts/update-examples/users.ts
@@ -26,6 +26,9 @@ example(
         nb: 3,
         perfType: "blitz",
       },
+      query: {
+        page: 1,
+      },
     },
   }),
 );

From 056a64dd67c8547530f1d8207dbc545c35992426 Mon Sep 17 00:00:00 2001
From: johndoknjas <jdoknjas@sfu.ca>
Date: Sun, 26 Apr 2026 22:38:32 -0700
Subject: [PATCH 2/4] clarify slightly

---
 doc/specs/tags/users/api-player-top-nb-perfType.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/specs/tags/users/api-player-top-nb-perfType.yaml b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
index 7a5d3888..ba119b50 100644
--- a/doc/specs/tags/users/api-player-top-nb-perfType.yaml
+++ b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
@@ -11,7 +11,7 @@ get:
   parameters:
     - in: path
       name: nb
-      description: How many users to fetch
+      description: How many users to fetch on the page of interest
       schema:
         type: integer
         minimum: 1

From 8b47848194d37fa4b8053c7dfe35fb19a7221602 Mon Sep 17 00:00:00 2001
From: johndoknjas <jdoknjas@sfu.ca>
Date: Sun, 26 Apr 2026 23:02:44 -0700
Subject: [PATCH 3/4] Try to clarify docs more.

---
 doc/specs/tags/users/api-player-top-nb-perfType.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/specs/tags/users/api-player-top-nb-perfType.yaml b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
index ba119b50..956a1d30 100644
--- a/doc/specs/tags/users/api-player-top-nb-perfType.yaml
+++ b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
@@ -11,7 +11,7 @@ get:
   parameters:
     - in: path
       name: nb
-      description: How many users to fetch on the page of interest
+      description: The number of users to get, from the 100 users on the leaderboard page of interest (see the `page` query param)
       schema:
         type: integer
         minimum: 1
@@ -41,7 +41,7 @@ get:
       required: true
     - in: query
       name: page
-      description: Leaderboard page number
+      description: The leaderboard page of interest (e.g., page 2 contains the top 101-200 players)
       schema:
         type: integer
         minimum: 1

From 8eccc303b9c390afd320e53052a4cbdfc8b566fe Mon Sep 17 00:00:00 2001
From: johndoknjas <jdoknjas@sfu.ca>
Date: Mon, 27 Apr 2026 20:02:19 -0700
Subject: [PATCH 4/4] Change from a 'page' parameter to an 'offset'.

---
 .../tags/users/api-player-top-nb-perfType.yaml     | 14 +++++++-------
 scripts/update-examples/users.ts                   |  2 +-
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/specs/tags/users/api-player-top-nb-perfType.yaml b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
index 956a1d30..69a6fc18 100644
--- a/doc/specs/tags/users/api-player-top-nb-perfType.yaml
+++ b/doc/specs/tags/users/api-player-top-nb-perfType.yaml
@@ -11,7 +11,7 @@ get:
   parameters:
     - in: path
       name: nb
-      description: The number of users to get, from the 100 users on the leaderboard page of interest (see the `page` query param)
+      description: How many users to fetch
       schema:
         type: integer
         minimum: 1
@@ -40,14 +40,14 @@ get:
           - threeCheck
       required: true
     - in: query
-      name: page
-      description: The leaderboard page of interest (e.g., page 2 contains the top 101-200 players)
+      name: offset
+      description: How many of the top players to optionally skip before getting `nb` users. Must be divisible by 100.
       schema:
         type: integer
-        minimum: 1
-        maximum: 20
-        default: 1
-        example: 1
+        minimum: 0
+        maximum: 1900
+        default: 0
+        example: 0
       required: false
   responses:
     "200":
diff --git a/scripts/update-examples/users.ts b/scripts/update-examples/users.ts
index cbef5da7..3a7031fb 100644
--- a/scripts/update-examples/users.ts
+++ b/scripts/update-examples/users.ts
@@ -27,7 +27,7 @@ example(
         perfType: "blitz",
       },
       query: {
-        page: 1,
+        offset: 0,
       },
     },
   }),