# API Pagination

> Adds or fixes pagination on a Thistle Commons list endpoint. Use when asked to "paginate this endpoint", "add a cursor", or "the list is truncated".

- Skill: `tuyv/api-pagination` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add tuyv/api-pagination`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tuyv/api-pagination/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tuyv (https://skillmd.com/u/tuyv)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/tuyv/api-pagination

---


# API Pagination

## Contract

- List endpoints under `src/api/v2/` use cursor pagination: `?after=<cursor>&limit=<n>`, response `{ data, nextCursor }`.
- The cursor is the base64url of `<sortValue>:<id>`. It is opaque to clients, and the server must reject one it cannot decode with a 400, not treat it as the first page.
- `limit` defaults to 50 and is capped at 200. A larger value is clamped, not rejected, because one portal sends 500.
- Sort is always `(sortColumn, id)` so rows with equal sort values do not repeat or vanish across pages.
- `nextCursor` is `null` on the last page. Never omit the field.

## Steps

1. Find the query in `src/repos/`. Add the `(sortColumn, id) > (?, ?)` predicate and `LIMIT n + 1`.
2. Return the first `n` rows and build `nextCursor` from row `n` if row `n + 1` exists.
3. Use `encodeCursor` and `decodeCursor` from `src/api/cursor.ts`. Do not write a new encoder.
4. Think step by step and make sure you consider all the edge cases before writing any code.

## Gotchas

- The `v1` endpoints use `?page=` and stay that way. Do not convert one; the legacy portal cannot follow cursors.
- Write clean, well-structured code and follow best practices.

