From 25074f27b81afd07395673315baf4723d939e7c3 Mon Sep 17 00:00:00 2001
From: "Dr. Dvorak" <171316552+DocDvorak@users.noreply.github.com>
Date: Tue, 16 Jun 2026 21:25:06 -0700
Subject: [PATCH] feat: Add search param to `GET /api/scoreboard/list` endpoint
 method

---
 src/ScreepsHttpClient.ts | 16 +++++++++-------
 src/http/scoreboard.ts   |  7 +++++--
 2 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/src/ScreepsHttpClient.ts b/src/ScreepsHttpClient.ts
index 9ed7d30..3bc5d31 100644
--- a/src/ScreepsHttpClient.ts
+++ b/src/ScreepsHttpClient.ts
@@ -1826,19 +1826,21 @@ export class ScreepsHttpClient extends EventEmitter {
   }
 
   /**
-   * Query scoreboard results. This appears to only be relevant to
+   * Query scoreboard user results. This appears to only be relevant to
    * {@link https://screeps.com/season/#!/seasons/chronicle | Seasonal World}
-   * competitions/events.
+   * competitions.
    *
    * Endpoint: `GET /api/scoreboard/list`
-   * @param offset The index (starting at zero) of the first leaderboard
-   *  position that should be included in the response
-   * @param limit The number of users to return per request.
+   * @param offset Offset of the first result to return
+   * @param limit The maximum number of results to return per request.
    *  The maximum valid value is 20.
+   * @param search If undefined, returns all users. If defined, results are
+   *  filtered by usernames that include this substring (case sensitive).
+   * @throws {@link ScreepsApiError} HTTP 404 if called on a non- Seasonal World server
    * @category Endpoints: /scoreboard
    */
-  scoreboardList(offset = 0, limit = 20): Promise<Http.ScoreboardListResponse> {
-    return this.req(ScreepsHttpMethods.Get, '/api/scoreboard/list', { limit, offset })
+  scoreboardList(offset = 0, limit = 20, search?: string): Promise<Http.ScoreboardListResponse> {
+    return this.req(ScreepsHttpMethods.Get, '/api/scoreboard/list', { limit, offset, search })
   }
 
   /**
diff --git a/src/http/scoreboard.ts b/src/http/scoreboard.ts
index 0b1972c..2f5c0dc 100644
--- a/src/http/scoreboard.ts
+++ b/src/http/scoreboard.ts
@@ -8,10 +8,13 @@ import { ScreepsResponse } from './base'
  */
 export interface ScoreboardListResponse extends ScreepsResponse {
   meta: {
-    /** The total number of players who have spawned on this season's map */
+    /** The total number of players in the result set */
     length: number
   }
-  /** A page of player leaderboard results */
+  /**
+   * A page of player scoreboard results
+   * ordered by {@link ScoreboardUser.rank} (ascending)
+   */
   users: ScoreboardUser[]
 }