Developers

On this page
Using the API

Paging

Lists come back a page at a time. Transmission feeds and classified ads page with a cursor; other lists page by number. Either way, follow hasMore until it's false.

The list envelope

A list is an object with two parts: data, the page's items, and paging, which says how to get the next page.

JSON
{
  "data": [
    { "transmissionId": "3f2c8a51-7d4e-4b9a-9c1e-2a6f0b8d5e17", "...": "..." }
  ],
  "paging": {
    "nextCursor": "NjM5MTMyNTE2MDAwMDAwMDAwOjhmMTRlNDVmY2VlYTRjMmE5YjNkMWU2ZjVhN2MyZDkw",
    "hasMore": true,
    "newestCursor": "NjM5MTMyNTE5MDAwMDAwMDAwOjJhOWIzZDFlNmY1YTdjMmQ5MDhmMTRlNDVmY2VlYTRj"
  }
}

A list with nothing in it has an empty data, not a 404. A few responses aren't in the envelope:

  • Short lists come back as a plain array, with no paging: hub categories, classified categories and subcategories, a Site's event years, both searches (at most 10 results each) and emoticons.
  • A Site's catalog home is an object of its own: the Site, its categories, and featured and recent products.
  • A catalog category is { category, products, paging }: the products are in products, not data.
  • A single resource, such as a profile or one transmission, is the resource itself.

Two kinds of list

List How you page Page size
Transmission feeds: a user's, a Site's, a hub's, a hashtag's cursor take: 1–25, default 20
A category's classified ads cursor take: 1–100, default 20
Followers, following, hub members, hubs in a category, a Site's events page, up to 1000 pageSize: 1–100, default 20
A catalog category page, up to 34 Always 30

Cursor lists

Cursor lists are newest first. To read one:

  1. Call it without a cursor to get the newest page.
  2. While paging.hasMore is true, call it again with cursor set to the last page's paging.nextCursor. Each page is older than the one before.
  3. When hasMore is false, you've reached the end, and nextCursor is null.
Shell
curl "https://api.blazot.com/v2/users/exampleuser/transmissions?take=25&cursor=NjM5MTMyNTE2MDAwMDAwMDAwOjhmMTRlNDVmY2VlYTRjMmE5YjNkMWU2ZjVhN2MyZDkw" \
  --header "Authorization: Bearer $BLAZOT_TOKEN"

Send the same parameters with every page. take, a hashtag feed's tags, and on account feeds includeRelays and includeHubTransmissions aren't part of the cursor.

Go by hasMore, not by how many items came back. A page can hold fewer than take items, or none, and still have more after it: an account feed leaves out a relay whose original you can't see, and with a Site's key, every transmission feed leaves out transmissions from accounts that have blocked the Site's owner.

User, Site and hashtag feeds also give a newestCursor, for fetching only what's new since you last looked: see Polling for new transmissions. Hub feeds and classified ads have none, and neither does a page fetched with cursor.

Cursors are opaque

Pass a cursor back exactly as you got it. Don't build one, change one, or read meaning into its contents: what's inside can change without notice. Use a cursor only with the list it came from. A cursor the API can't read is a 400, and on the feeds you can poll, sending both cursor and newerThan is a 400 too.

Page-numbered lists

Ask for a page by number, from 1, and say how many items you want with pageSize:

Shell
curl "https://api.blazot.com/v2/users/exampleuser/followers?page=2&pageSize=100" \
  --header "Authorization: Bearer $BLAZOT_TOKEN"
JSON
{
  "data": [
    { "userName": "anotheruser", "...": "..." }
  ],
  "paging": {
    "page": 2,
    "pageSize": 100,
    "hasMore": true
  }
}

While hasMore is true, ask for page + 1, with the same pageSize, and for a Site's events the same year. A page past the end of the list has an empty data; a catalog category answers 404 instead.

  • The deepest page is 1000 (34 for a catalog category, which pages 30 products at a time and takes no pageSize). A higher number is served as that page, and paging.page shows the page you got. hasMore is always false there, so paging stops even if the list goes on. A catalog category with fewer than 34 pages answers 404 to a higher number, as a page past the end.
  • Lists can shift while you page. Each page is counted from the start of the list as it stands when you ask, so a new follower or event added in between can move items from one page to the next. Expect an occasional repeat, and key items by their username or id.

Out-of-range values

Paging values outside their range are brought into it, not refused:

  • A take or pageSize above its maximum is lowered to the maximum; zero or less gives the default (20).
  • A page of zero or less gives page 1; above the deepest page gives the deepest page.

A page-numbered list's paging shows the page and pageSize it used, so you can see when a value was changed. A cursor list doesn't echo take. A value that isn't a number at all, such as take=abc, is a 400: see Errors.