Harbor REST API pagination inconsistency between repository listing and global search endpoints

Integration boundary

Harbor v2.x exposes two distinct pagination contracts: the project-scoped repository and artifact endpoints use page (1-based) and page_size (max 100), while the global search endpoint /api/v2.0/search uses limit and offset. A client that must both enumerate all repositories in a project and perform cross-project searches therefore needs to implement two pagination strategies against the same API version.

Goal and constraints

The goal is to design a reusable pagination layer that can consume both endpoint families without duplicating cursor management, rate-limit handling, or token-refresh logic. Constraints include the hard page_size=100 ceiling on project-scoped endpoints, the absence of cursor-based pagination (so concurrent pushes/deletes can shift offsets), and the fact that X-Total-Count may be approximate for very large repositories. Harbor 2.10+ adds X-Pagination-Limit and X-Pagination-Page response headers, but older versions only return X-Total-Count.

Open questions

1. Is there a supported way to retrieve a stable snapshot identifier (e.g., a registry generation token) that would let a client paginate consistently across both endpoint families despite concurrent mutations?
2. Does the q filter syntax on /api/v2.0/search accept the same field names as the project-scoped repository listing, or must the client maintain two filter translators?
3. For Harbor deployments before 2.10, what is the recommended pattern to detect the pagination contract version at runtime without parsing Swagger?