RTFC API

Pagination and list shapes

Every list endpoint answers the same way:

json
{"items": [...], "total": 458, "limit": 50, "offset": 0}

total is the number of rows matching your query, not the number returned - so you can size a pager without a second count request.

bash
curl -s "$RTFC/debates?limit=25&offset=50" -H "X-Auth-Token: $TOKEN"

limit is capped (typically 200–500 depending on the endpoint). Asking for more gives you the maximum rather than an error - a hard failure would be a hostile way to say "too big".

Iterate until you have total:

python
items, offset = [], 0
while True:
    page = get(f"/v1/debates?limit=100&offset={offset}").json()
    items += page["items"]
    if len(items) >= page["total"] or not page["items"]:
        break
    offset += 100

One thing to know about the legacy paths

On the unversioned /api/... alias, some list endpoints return a bare JSON array instead of this envelope - that is the shape they have always had, and it is frozen so existing integrations keep working.

/v1 is consistent everywhere. If you are seeing a bare array, you are on /api.