A Link Header and Cursor Contract Your SDK Can Generate

Define the cursor as a signed, opaque token with a fixed schema. Five fields cover almost every collection endpoint:

The tie-breaker matters. A timestamp alone is not unique, and without a second column in the ORDER BY the database has no deterministic order for rows that share a timestamp, so items can be missed or duplicated between pages the keyset guide on search pagination. Store both the sort column and the primary key in k, and use a tuple comparison in SQL, or a search_after-style value where the backend supports it.

The filter hash binds the cursor to the query that produced it. If a client changes status=open to status=closed and replays an old cursor, the hash will not match and the server rejects the request with a 400 rather than returning a plausible but wrong page. The expiry caps how long a stale cursor can circulate: fifteen minutes suits most UI scrolls, while exported batch jobs can ask for a longer server-side window that the issuer controls.

A worked example makes the cost clear. Suppose a collection has 50 million rows, you return 50 per page, and a client scrolls to page 5,000. With offset, the query reads about 250,000 rows to return 50. With keyset, the database seeks directly to the cursor value through the index and reads 50 rows plus index overhead. The page cost stops growing with depth. The design trade-off is that clients lose random access and total counts, which is exactly what Contentful removed when it moved its content APIs to cursor pagination Contentful's pagination post.

Sign the encoded payload with HMAC-SHA256 and keep the key on the server. The token on the wire is base64url(payload) + "." + base64url(mac). Sign the base64url payload bytes themselves, not the JSON, so the exact string a client sends back is the exact string you verify. Use a constant-time comparison; a naive == comparison on a MAC is a timing side channel.

import base64, hmac, hashlib, json, time

def b64e(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

def b64d(text: str) -> bytes:
    pad = "=" * (-len(text) % 4)
    return base64.urlsafe_b64decode(text + pad)

def encode_cursor(keys, filter_hash, direction, ttl, key_id, secret):
    payload = {"v": 1, "k": keys, "f": filter_hash, "d": direction,
               "e": int(time.time()) + ttl, "kid": key_id}
    body = json.dumps(payload, separators=(",", ":")).encode()
    token = b64e(body)
    mac = hmac.new(secret, token.encode(), hashlib.sha256).digest()
    return f"{token}.{b64e(mac)}"

def decode_cursor(token, secrets_by_id):
    token_b64, mac_b64 = token.split(".")
    payload = json.loads(b64d(token_b64))
    secret = secrets_by_id.get(payload["kid"])
    if secret is None:
        raise ValueError("unknown key id")
    expected = hmac.new(secret, token_b64.encode(), hashlib.sha256).digest()
    if not hmac.compare_digest(expected, b64d(mac_b64)):
        raise ValueError("bad signature")
    if payload["e"] < time.time():
        raise ValueError("cursor expired")
    return payload

Two decisions are worth writing down. First, include the key id in the signed payload so rotation can run without a flag day: old cursors verify with the old key, new cursors are issued with the new one. Second, reject a filter hash mismatch before you touch the database. This makes cursors idempotent under retries and safe to treat as bears of state.

A forged cursor in the offset world lets a client request an arbitrary page number. A forged cursor here lets a client request arbitrary sort key values, which can be worse: it can skip ahead to records the user should not see if the sort key aligns with a cheaper query path, or it can pass a filter hash that no longer matches the row-level policy. That is why cursors are opaque. Clients must not parse, decode, or rebuild them, and your SDK should not encourage it.

For cursor errors, return a standard problem detail body rather than an ad hoc error shape. RFC 9457 defines a JSON problem detail with an application/problem+json media type that machines can parse RFC 9457, and the Swagger guide explains why inventing a custom error format costs integration time and money the Swagger problem details guide. A cursor that fails verification should come back with a stable type URI such as https://api.example.com/problems/invalid-cursor, so every SDK can map it to the same retry decision.

The response should publish navigation, not hide it. RFC 8288 defines the Link header and its relation types RFC 8288, and the practical guide to Link pagination explains that clients read the URL labeled next and request it rather than constructing a new URL Vincent Schmalbach on Link header pagination. GitHub documents prev and next; Shopify uses previous and next and requires its page_info value to be reused exactly, so the client must not assume a relation name or parameter shape Schmalbach's Link header guide.

A page response then looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://api.example.com/v1/tickets?cursor=eyJ2IjoxLC...&limit=50>; rel="next",
      <https://api.example.com/v1/tickets?cursor=eyJ2IjoxLC...&limit=50&dir=prev>; rel="prev"

{"items":[...],"has_more":true}

Three rules keep it honest. Omit the next link entirely on the last page, because the absence of the relation is the documented end signal. Do not emit prev when the current request has no cursor. And never express page size or filters in the link if they were not part of the signed contract: the link should be the exact URL the client can replay, with the cursor as the only state that changes.

The Link header also lets the API describe itself to search and other clients. Google's own guidance confirms that rel="next" and rel="prev" are supported in the HTTP header as well as in the document head the Stack Overflow answer quoting Google. That is a free win for crawlable listings.

The real leverage is to write the contract once and generate everything else. A minimal spec needs four parts: the cursor payload schema, the signing algorithm and test vectors, the Link header format, and the endpoint shape. Once those are in a machine-readable file, each language helper is mechanical and reviewable.

The test vectors are what keep languages from drifting. Generate a handful of known payloads with a known key and record the exact tokens. Every SDK runs the same vectors in its test suite; the day a Python helper and a Go helper disagree about JSON key order inside the payload, the vectors fail before a customer sees a mismatched cursor. Since the signed bytes are the base64url payload, the payload must be serialized canonically: fixed field order, no whitespace, no integer formatting differences. The test vectors catch all of it.

The generated helpers should expose a small surface: a Page object with items, next, prev, and a client method that follows next until it is absent. Keep the raw cursor out of the public type. If a user needs to resume a traversal later, give them an opaque checkpoint string and a resume(checkpoint) call.

For the TypeScript helper, a paginate function that takes a URL and a fetch-like function is the whole contract:

type Page<T> = { items: T[]; next: string | null; prev: string | null };

async function* paginate<T>(url: string, get: (u: string) => Promise<{ body: { items: T[] }; links: { next?: string } }>) {
  let current: string | undefined = url;
  while (current) {
    const res = await get(current);
    yield* res.body.items;
    current = res.links.next;
  }
}

Because the helper only follows links, a server change that adds a page-size cap or a new parameter does not require an SDK release. That is the payoff of publishing navigation over rebuilding URLs.

If you are generating clients while also calling models for classification, embedding, or extraction inside the same service, keeping the credential and retry logic in one place helps. Quanta Inference offers text, image, video, audio, and embedding models through one OpenAI-compatible API key Quanta Inference, which is a separate contract from the paging one but the same principle: one interface, many models.

Cursors are a wire format, and wire formats change. Version them. API versioning exists precisely to let a producer make breaking changes without breaking existing clients the Postman guide to API versioning. The Speakeasy guide draws the practical line: additive changes like new response fields are usually safe, while renaming or removing fields is a breaking change the Speakeasy versioning guide. The v field in the cursor is your escape hatch. Increment it when the payload schema or signing bytes change, then reject old cursors with a problem detail that tells the client to restart from page one.

Key rotation needs its own plan because cursors outlive deploys. Run two keys live at all times: a current key for signing and a previous key for verifying. Rotate on a schedule that is shorter than your maximum cursor lifetime, publish the new key id to each server instance, and drop the oldest key only after every cursor signed with it has expired. If you skip this, a rotation will reject every in-flight scroll on the platform at once.

The deprecation path has three stages. First, accept both the old and new cursor versions during a migration window and log which one arrives. Second, return a Deprecation and Sunset style signal in the problem detail for old cursors, pointing to the changelog. Third, reject old cursors only after your published window closes. Backward compatibility tests belong in CI: assert that an old-version cursor still verifies for the whole window and fails cleanly on the last day.

Then keep the contract where clients can find it. A changelog that documents each cursor version and any field additions is one of the most important reference documents an API consumer has the xMatters API versioning guide. If several teams own servers and SDKs, generating the helpers, the test vectors, and the docs from one file turns coordination into a build step.

• The cursor contains sort keys with a unique tie-breaker, a filter hash, a direction, an expiry, and a version.
• The signature covers the encoded payload exactly, with constant-time comparison and a key id.
• Cursor verification failures return an RFC 9457 problem detail with a stable type URI RFC 9457.
• Responses emit Link headers with rel="next" and rel="prev", and omit next on the last page RFC 8288.
• Every target language passes the same signing and parsing test vectors.
• Two signing keys are live, and rotation is tied to cursor lifetime.
• A version field and a documented deprecation window exist before the second consumer integrates.

If the team that consumes these APIs is building with coding agents, the generated helpers pair well with skills the agent can install. Quanta Skills is a library you can drop into a coding agent or assign to an expert Quanta Skills, which is useful when the same team wants the paging client and the model calls built to one contract.