Developers

On this page
More

Moving from v1

Version 2 reads more of Blazot, pages with cursors, polls for new transmissions and reports errors the same way everywhere. This guide maps each version 1 call to version 2 and lists what changes.

Version 1 still works, so you can move one call at a time: your keys and your token work for both versions. Version 1's paths and parameters are in its OpenAPI document. A new app doesn't need this guide: start with the Quickstart.

The calls

  • GET /auth/token becomes GET /v2/auth/token.
  • GET /transmissions/{username} becomes GET /v2/users/{username}/transmissions, or with a Site's key GET /v2/sites/{siteName}/transmissions.
  • GET /hashtag?t={tag} becomes GET /v2/hashtags/transmissions?tag={tag}, or GET /v2/hashtags/{tag}/transmissions for one tag.
  • GET /events/{username}?year={year} becomes GET /v2/sites/{siteName}/events?year={year}.

If your client sends X-Version: 1.0 on every call, it can keep doing so: version 2 paths ignore the header.

Version 1's transmissions read included hub transmissions; includeHubTransmissions=true keeps that. Leave it out for the timeline without them.

Version 1's transmissions and events reads worked only for your own account. Version 2 reads any account your key's account can see; your own is just one of them. includeHubTransmissions still works only on your own timeline: on anyone else's it's a 403.

Getting a token

/v2/auth/token takes the same x-api-key and x-secret-auth-key headers and returns the same token, with one more field, expiresIn: seconds until the token expires. Both calls share one limit, 3 requests per 5 minutes.

A failed version 1 token call answers with a plain-text 401, or a 400 whose body is Internal Server Error. Version 2 answers a 401 with a Problem Details body: see Authentication.

Parameters

Version 1 Version 2
Transmissions' and hashtags' takeCount take: up to 25 transmissions a page, 20 by default. Version 1 allowed 20 on the transmissions read (5 by default) and 100 on hashtags (50 by default).
afterDate (older than a time) cursor, set to the last page's nextCursor: see Paging
sinceDate (newer than a time) newerThan, set to the last response's newestCursor: see Polling
t tag, repeated for each tag. More than 10 tags is a 400; version 1 used the first 10.
imageWidth Gone. A link preview's image comes as stored, at most 920 pixels wide; media images come at their own size, as before.
Events' skipCount and takeCount page, from 1, and pageSize, up to 100 a page, 20 by default
Events' year, required year, optional: without it you get the current year, or the latest year with events if the current year has none

A stored date can't become a cursor. Read the newest page once without a cursor, then keep the nextCursor and newestCursor it gives you.

Polling differs from sinceDate in two ways: a poll returns only transmissions at least a minute old, and a transmission can come back twice. Store transmissions by transmissionId and let a later copy replace the earlier one: see Polling.

Responses

  • Text is no longer HTML-encoded. Version 1 sent body and displayName HTML-encoded (an & came as &). Version 2 sends plain text. A version 1 client that put text straight into a page must now escape it, or a transmission can add markup to your site: see Rendering.
  • Lists come in an envelope, { data, paging }, not as a bare array: see Paging.
  • Errors are Problem Details with a code to match on, instead of plain text: see Errors.
  • Times end in Z, marking them as UTC. Version 1's times were UTC too, but didn't say so. Event start and end times are still the event's local time: see Rendering.
  • Transmissions rename interactionsMinimal to interactions, drop media's always-empty videoUrl (show the cover and link it to the transmission's url), and add url, dateEdited, pinned and containsSensitiveMedia. author gains url, and its subscriptionLevel is always 0 for an account without a subscription (version 1 could send null or an old level).
  • Polls add totalVotes and each choice's isYourChoice. A choice's voteCount is null until your account has voted or the poll has ended, as on Blazot; version 1 always sent the counts.
  • Profile, link-preview and event images are on Blazot's CDN (cdn-img.blazot.com): version 1 served them from blazot.com/media/image/.... Media images were already there.
  • A plain relay whose original you can't see is left out of an account's timeline, so a page can hold fewer transmissions than take.
  • Events: the list gives a summary of each event; read the whole event at /v2/sites/{siteName}/events/{eventId}. The address fields locality, region and zipPostcode are now city, stateProvince and postalZipCode, dateEnd is null for an event without an end time; version 1 sent 0001-01-01T00:00:00. A summary's image is imageUrl, and the whole event's is an image object; both are null when there's no image, where version 1 always sent an object.

The API reference has every field.

Rate limits

Version 2 has one read budget per account, the size of version 1's three budgets put together, and it's separate from them: version 1 reads don't spend it. Page sizes changed, so the same number of transmissions can take more or fewer reads: see Rate limits.