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/tokenbecomesGET /v2/auth/token.GET /transmissions/{username}becomesGET /v2/users/{username}/transmissions, or with a Site's keyGET /v2/sites/{siteName}/transmissions.GET /hashtag?t={tag}becomesGET /v2/hashtags/transmissions?tag={tag}, orGET /v2/hashtags/{tag}/transmissionsfor one tag.GET /events/{username}?year={year}becomesGET /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
bodyanddisplayNameHTML-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
codeto 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
interactionsMinimaltointeractions, dropmedia's always-emptyvideoUrl(show the cover and link it to the transmission'surl), and addurl,dateEdited,pinnedandcontainsSensitiveMedia.authorgainsurl, and itssubscriptionLevelis always0for an account without a subscription (version 1 could sendnullor an old level). - Polls add
totalVotesand each choice'sisYourChoice. A choice'svoteCountisnulluntil 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 fromblazot.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 fieldslocality,regionandzipPostcodeare nowcity,stateProvinceandpostalZipCode,dateEndisnullfor an event without an end time; version 1 sent0001-01-01T00:00:00. A summary's image isimageUrl, and the whole event's is animageobject; both arenullwhen 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.