Concepts
What the API reads, in Blazot's own words, and the one rule that shapes every response: you read as the account your key belongs to.
Users and Sites
Blazot has two kinds of account:
- Users are people. Read a profile at
/v2/users/{username}. - Sites are business accounts that users create and manage. Read one at
/v2/sites/{siteName}. A Site has its own transmissions, events and catalog.
Both send transmissions. A transmission's author is either; when it's a Site, the author's userName is the Site's name.
You read as your key's account
An API key belongs to one account: your user account, or a Site you manage. Every call made with its token reads Blazot as that account, so you see what that account would see on Blazot:
- Transmissions from accounts that have blocked it, or that it ignores, are left out, and reading a user who has blocked it is a
404. With a Site's key, transmissions from accounts that have blocked the Site's owner are left out too, and reading a user who has blocked the owner is a404. - Accounts that aren't available (disabled, deleted or suspended) are left out, and reading one directly is a
404. - Private hubs' transmissions and hubs' member lists depend on the account's own hub memberships (see Hubs).
So a user's key and a Site's key can get different results for the same call. Use the key of the account whose view you want. Some reads, such as user and hashtag search, give the same results whoever asks.
The API also can't tell you why something is missing. A 404 means it doesn't exist or this account can't see it, and the two look the same on purpose.
Transmissions
Blazot calls a message a transmission. Each one has a transmissionId, its text in body (plain text, which can be empty), the time it was sent in dateTransmitted, and its url: its page on Blazot. Timelines and feeds list transmissions newest first.
- Responses: a transmission that answers another has the parent's id in
parentItemId. It'snullon a transmission that isn't a response. - Relays: a relay passes another transmission on, with or without a comment of its own. The original is in
relayedTransmission, one level deep: the original's ownrelayedTransmissionis alwaysnull. It's alsonullwhen your account can't see the original, for example because it was deleted. On an account's timeline, a relay without a comment whose original you can't see is left out altogether, so a page can hold fewer transmissions than you asked for. Timelines include relays unless you sendincludeRelays=false. - Pinned: an author can pin a transmission to their profile. It has
pinned: truebut stays in date order: the API doesn't move it to the top. - Edits:
dateEditedis when the text was last edited, ornullif it never was. - Interactions:
interactionscounts its reactions, responses and relays. - Polls: a poll is in
poll, with itstotalVotesandchoices; it'snullon a transmission without one. As on Blazot, a choice'svoteCountisnulluntil your account has voted or the poll has ended, andisYourChoicemarks your vote. A Site can't vote, so a Site's key sees the counts only once the poll has ended.
Hubs
Hubs are groups around a topic, sorted into hub categories. A hub's details (/v2/hubs/{hubName}) are visible to everyone, unless the hub itself isn't available, for example because it was deleted. The rest depends on the hub:
- Transmissions: a public hub's are visible to everyone; a private hub's only to its approved members. Anyone else gets a
404, including someone whose request to join is still waiting and an admin who hasn't joined. - Members: in any hub, public or private, the list is visible only to its approved members and its admins. Anyone else gets a
404.
Transmissions sent in a hub stay out of account timelines unless you ask for them, and you can ask only on your own timeline: includeHubTransmissions=true on your key's account. On anyone else's timeline it's a 403. Read a hub's own feed at /v2/hubs/{hubName}/transmissions.
Media
A transmission's media lists its images and its video's cover:
- An image has
imageUrlset, withimageWidthandimageHeight. - A video appears as its cover image in
videoCover, with the video's size. The API doesn't give the video itself: link the cover to the transmission'surl, where it plays on Blazot.
The video's cover comes first, then the images. An animated GIF is in animatedMedia instead.
When containsSensitiveMedia is true, the author marked the media as sensitive. Show it only after the viewer chooses to, as Blazot does.
Showing what you read
Text fields such as body, displayName and bio are plain text, not HTML: written by Blazot's users, or for a link preview taken from the linked page. Escape them before putting them in a web page, or a transmission could inject markup into your site. Link URLs, such as a link preview's linkUrl, are always http or https (or empty), but users choose where they lead. Rendering safety and JSON conventions has more.
Everything else
Site events, Site catalogs, classified ads, hub categories, search and emoticons each have their own section in the API reference, with what every field means. Errors explains the 404s and 403s mentioned here.