Pagination

KATforge uses page-based pagination for list endpoints. The wire format is the same everywhere:

JSON

{
   "body": [ /* items */ ],
   "pagination": {
      "page":     1,
      "limit":    50,
      "total":    1240,
      "has_more": true
   }
}

Query parameters

Parameter	Default	Notes
`page`	`1`	1-indexed
`limit`	varies (typically 20–50)	Hard cap at 100
`cursor`	none	Cursor-based for endpoints that support it

shell

curl 'https://api.katforge.com/v1/games/lextris/leaderboard?mode=daily&page=2&limit=20'

With the SDK

The SDK wraps every paginated endpoint in a PaginatedResponse helper. You can use it three ways:

1. Async iteration

The most common pattern. Iterates every entry across every page automatically:

TypeScript

for await (const entry of katforge.games.lextris.leaderboard ({ mode: 'daily' })) {
   console.log (entry.display_name, entry.score);
}

2. Single page

For pagination UI where you want one page at a time:

TypeScript

const result = await katforge.games.lextris
   .leaderboard ({ mode: 'daily', page: 1, limit: 20 })
   .page ();

console.log (result.body);          // The 20 entries
console.log (result.pagination);    // { page, limit, total, has_more }

3. Collect all

For small result sets where you want everything in one array:

TypeScript

const all = await katforge.games.lextris
   .leaderboard ({ mode: 'daily' })
   .all ();

Server-side filters

Most paginated endpoints accept domain-specific filters in the query string. For example, the Lextris leaderboard takes mode, period, timezone, and username:

TypeScript

const top = await katforge.games.lextris
   .leaderboard ({
      mode:     'daily',
      period:   'this_week',
      timezone: 'America/Los_Angeles',
      limit:    100
   })
   .page ();

When username is supplied and the user isn't already in the returned page, the API appends their entry so the UI can always show "you" alongside the top players.

Cursor-based endpoints

A handful of endpoints (typically very large feeds) support cursor-based pagination instead. The pagination block returns a cursor field instead of page:

JSON

{
   "body":      [ ... ],
   "pagination": {
      "cursor":   "eyJpZCI6MTIzNH0=",
      "limit":    50,
      "has_more": true
   }
}

The SDK abstracts this away — for await works identically for cursor-based and page-based endpoints.