Pagination contract

All list endpoints in Mnemosyne use cursor-based pagination. We deliberately don’t offer offset/limit because offset pagination breaks silently when rows are inserted between pages.

Shape

GET /v1/facts?cursor=eyJpZCI6Imxhc3RfaWQifQ==&limit=50

{
  "items": [ … ],
  "next_cursor": "eyJpZCI6Im5leHRfaWQifQ==",
  "has_more": true
}

• limit defaults to 50, max 200.
• next_cursor is opaque — clients store it and pass it back as-is.
• When has_more is false, next_cursor is null.

Encoding

The cursor is a base64-encoded JSON blob with the sort key of the last item on the current page. We don’t promise the inner format is stable — clients must treat it as opaque. Don’t decode and reshape.

Time-travel pagination

Read endpoints accept asOf (see Bitemporal model). The cursor returned for an asOf request can only be used with the same asOf — mixing them returns 400 invalid_cursor.

Streaming

For very large exports the /v1/export endpoint streams JSONL instead of paginating. That’s the preferred way to move > 50 000 rows.