Paging

The shape

A list answers with its rows, how many match altogether, and a cursor for the page after, or null on the last page:

{
  "documents": [ "…" ],
  "total": 412,
  "next_cursor": "eyJkIjoiMjAyNi0wOS0xMiIsImlkIjoi…"
}

Send next_cursor back as cursor with the same filters to get the next page. limit is the page size (50 by default on the documents, 200 at most).

curl "https://api.thawed.app/v1/documents?type=utilities/electric-bill&limit=50" \
  -H "Authorization: Bearer $THAW_TOKEN"

curl "https://api.thawed.app/v1/documents?type=utilities/electric-bill&limit=50&cursor=eyJkIjoiMjAyNi0wOS0xMiIsImlkIjoi…" \
  -H "Authorization: Bearer $THAW_TOKEN"

Why a cursor and not a page number

Documents arrive on their own: email-in, a folder watched, a phone. With page numbers, a document that arrives while you are on page 3 pushes every later row down one, and the first row of page 4 is the last row of page 3 again. A cursor is the position of the last row you saw - its date and its id - and the next page is everything after that position, whatever arrived in the meantime. No row is repeated and none is skipped.

That also means a cursor is bound to its ordering and its filters. Change the filters or the sort, and start again without one. A cursor that is not one, or belongs to a different ordering, is a 400.

Ordering

Documents come newest first by the date on the document - the first known of the printed date, the period it covers, the day it was had before Thaw, and the arrival - so an undated import never floats to the top as a block. sort=arrival orders by when Thaw received it instead. Facts and the people & things come whole, in the orderings said on each endpoint.

Where there is no cursor

Most lists are whole: the Checkup is every open item, the facts are the first limit (200 at most) of the filters, newest document first, with their sums over everything that matched, the people & things are everyone, the bundles and the imports are all of them. Those answer with the list and no cursor, because paging what a page shows whole would only add a round trip. Search takes limit (50 at most) and answers with the best matches and no cursor either: past the first fifty a narrower question is the better next step.