Pagination & filtering

Every list endpoint returns the same envelope and paginates the same way, so one loop works for every resource.

The list envelope

{
  "object": "list",
  "url": "/v1/decks",
  "data": [{ "id": "deck_2a9f8c1b", "object": "deck" }],
  "has_more": true,
  "next_cursor": "ZGVja18yYTlm"
}

Pass ?limit= (1–100, default 20) and ?cursor= — the next_cursor from the previous page, verbatim. Cursors are opaque: never construct or decode one. When has_more is false, you've seen everything.

renza decks list --limit 50 --cursor ZGVja18yYTlm

The CLI's --all flag follows cursors for you and emits every page (as NDJSON under --json). It's opt-in, so a script gets a bounded response unless it asks for everything.

Filtering

Filters are top-level query params, documented per operation — e.g. GET /v1/decks takes ?status=, ?folder=, ?trashed=; GET /v1/comments takes ?deck=, ?resolved=, ?slide_index=. Range operators apply to comparables: ?created_at[gte]=2026-01-01T00:00:00Z.

Sorting

?order=created_at.desc (the default) or created_at.asc. Cursor pagination keys on (created_at, id), so the order is total and stable — a resource created between your pages can't shift what you've already seen.

Expansion

Relations are returned as id strings ("current_artifact": "art_7c1b…"). Fetch the related object with its own retrieve endpoint. (expand[] inlining is planned as an additive change — see Versioning.)