Pagination

List endpoints are cursor-paginated using a keyset (seek) cursor rather than numeric offsets. Keyset pagination doesn't skip or duplicate rows when the collection mutates mid-iteration — the approach Stripe and GitHub take.

Query parameters

The default order is newest first. Each endpoint documents its own sortable keys and default in the API reference; most default to created (the creation timestamp), descending.

Response envelope

Every list response has the same shape:

{
  "data": [
    { "id": "…" }
  ],
  "next_cursor": "eyJrIjoiY3JlYXRlZCIsImQiOiJkZXNjIiwidiI6Ii4uLiJ9"
}

• data — the page of results.
• next_cursor — an opaque string to fetch the next page, or null when there are no more pages.

There is no has_more flag and no Link header — next_cursor is the single signal. When it's null, you've reached the end.

Paging through results

Pass the returned next_cursor back as cursor to get the next page, and repeat until next_cursor is null:

# First page
curl "https://gallery.example/api/v1/gallery/artworks?limit=50" \
  -H "Authorization: Bearer gpk_…"

# Next page — feed back the previous next_cursor
curl "https://gallery.example/api/v1/gallery/artworks?limit=50&cursor=eyJrIjoi…" \
  -H "Authorization: Bearer gpk_…"

Notes

• The cursor is opaque — don't parse, construct, or mutate it. Pass back exactly what you received.
• A cursor is bound to the sort/dir it was minted with. Reusing a cursor with a different sort returns 400 invalid_request — keep sort/dir stable across a pagination run, or start over from the first page.
• Keep limit within 1–100; values outside the range are rejected as 400 invalid_request.