Pagination, filtering and sorting

Every collection route takes the same knobs. None of them are required.

curl -s "https://api.eu-par-1.interlaken.ai/api/v1/vms?limit=50&sort_by=name&order=asc" \
  -H "Authorization: Bearer $TOKEN"

Filtering

Any query parameter that is not one of the five above is treated as an exact-match filter on the field of that name:

# Every stopped VM
curl -s "https://api.eu-par-1.interlaken.ai/api/v1/vms?status=stopped" \
  -H "Authorization: Bearer $TOKEN"

Field names are the ones in the response body. Naming a field the response does not have, or giving a value that cannot be parsed as that field's type, is a 400 rather than an empty page, so a typo tells you it was a typo.

Filters combine with AND. There is no OR, and no range or partial-match operator: q is the tool for "contains".

Reading total

total counts the rows that matched after filtering and search, before limit and offset were applied. So it is the size of the result set you are paging through, which is what you want for a page count:

pages = ceil(total / limit)

Paging through everything

offset=0
while :; do
  page=$(curl -s "https://api.eu-par-1.interlaken.ai/api/v1/vms?limit=100&offset=$offset" \
    -H "Authorization: Bearer $TOKEN")
  echo "$page" | jq -c '.items[]'
  count=$(echo "$page" | jq '.items | length')
  [ "$count" -lt 100 ] && break
  offset=$((offset + 100))
done

Offset paging is consistent within a page but not across pages: something created while you are walking can shift rows between requests. For a stable walk, sort by created_at ascending, which only ever appends.

Cursors, where they exist

A few high-volume, append-only collections page by cursor instead, because offsets are the wrong shape for a log. The team conversation log is one: it returns a next value to pass back as ?after=. Those routes say so on their reference page.