Pagination

List operations return one page at a time. You choose the page size with limit and move to the next page with cursor.

Query parametersCopy Anchor Link

The responseCopy Anchor Link

A list response holds the items, the total count and the paging state:

{
  "broadcasts": [ ... ],
  "total": 134,
  "paging": { "next": "eyJvIjoyMH0", "hasMore": true }
}

• The list key is hubs, broadcasts or changes, depending on the operation.
• total is the number of items across all pages.
• paging.next is the cursor for the next page, and null on the last page.
• paging.hasMore says whether another page follows.

The change history has no total; see The change history is different.

To read the next page, pass paging.next back as ?cursor=, with the same filters. Treat the cursor as opaque: don't build or change one yourself. On a hub or broadcast list, a cursor the API cannot read returns the first page.

Read every pageCopy Anchor Link

This loop reads every broadcast in a hub, 100 at a time.

cursor=""
while :; do
  args=(-s -G -H "Authorization: Bearer $EVENTDOOR_TOKEN" --data-urlencode "limit=100")
  [ -n "$cursor" ] && args+=(--data-urlencode "cursor=$cursor")
  page=$(curl "${args[@]}" "$EVENTDOOR_API/organizations/acme/hubs/home-games/broadcasts")
  echo "$page" | jq -r '.broadcasts[].slug'
  [ "$(echo "$page" | jq -r '.paging.hasMore')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.paging.next')
done

Each page is one request against your rate limit. limit=all returns the whole list in one request, which also costs one.

FiltersCopy Anchor Link

Filters narrow a list before it is paged. Keep the same filters on every page of one read.

Broadcast listsCopy Anchor Link

List broadcasts in a hub and list an organization's broadcasts take:

state=live returns at most limit broadcasts in one response, with paging.hasMore false and no next, even when more are live. total counts every live broadcast. Pass limit=all to get them all, or compare total with the number returned.

curl -s -G -H "Authorization: Bearer $EVENTDOOR_TOKEN" \
  --data-urlencode "state=upcoming" \
  "$EVENTDOOR_API/organizations/acme/hubs/home-games/broadcasts"

Hub listsCopy Anchor Link

List hubs takes:

Filter by tag categoryCopy Anchor Link

All three lists also filter by tag: any other query parameter is read as a tag-category slug, and its value as a comma-separated list of tag slugs in that category. Within one category a row matches any of the tags; across categories it must match every category. For example, ?age_group=5-8,9-12&sport=swimming returns rows tagged 5-8 or 9-12 in age_group and also tagged swimming in sport.

Because an unrecognised parameter is read as a tag category, a misspelt filter returns an empty list rather than an error.

With at least one tag-category filter, add facets=true to get a facets array next to paging: for each category you filter on, its tags and how many rows would match each tag under your other category filters.

The change history is differentCopy Anchor Link

Listing a broadcast's changes pages the same way, with cursor and paging, with four differences:

• Its limit is 1-50, default 20. It has no all.
• An integer limit out of range, including 0, is clamped to 1-50. Anything else, including all, means 20, with no error.
• A cursor it cannot read is refused with 400 Invalid cursor instead of returning the first page.
• Its response has changes and paging only, with no total.