Developers

On this page
Using the API

Rendering safety and JSON conventions

What the API returns was written by Blazot's users, so treat it the way you'd treat anything a stranger typed into your site. This guide covers showing it safely, then the conventions every response follows.

Escape every text field

Text fields are plain text, not HTML: body, displayName and bio, hub and event descriptions, and product and classified ad text. A < in a transmission is a real < that someone typed. A link preview's title and description come from the linked page: treat them the same way.

  • Escape text for where it goes. In HTML, escape it as text, or set it with your framework's text binding (textContent in the DOM, not innerHTML). In an attribute, a script or a URL, use the escaping for that place.
  • Don't read it as Markdown or HTML. It isn't either, and treating it as one lets a transmission add markup to your page.
  • Mentions, hashtags and links in body are plain text. The API doesn't mark them up. If you link them, build the links yourself: a profile is at https://blazot.com/{username}, and a hashtag at https://blazot.com/hashtag/{tag} (the tag without its #), a page that opens only for people signed in to Blazot. A web address in body is a link its author chose, and nothing has checked it: link only http and https addresses, and treat them as the next section describes.

Links come in two kinds:

  • Links to Blazot. Most resources have a url: their page on Blazot, such as a transmission's or a profile's. Link back with it. A transmission sent in a private hub has a url too, but its page opens only for the hub's members. A url can be an empty string in rare cases, such as a catalog product whose Site's name can't form a page address; show no link then.
  • Links users chose. A link preview's webLink.linkUrl and an event's websiteLink are always http or https, and a product's externalUrl is always https. Any of them can be an empty string instead. They lead wherever their author chose, so open them as you would any outside link: in HTML, with rel="noopener noreferrer nofollow ugc", and show the link's address so people can see where it goes.

If you restrict image sources, for example in a Content Security Policy, these are the hosts: images (imageUrl, profileImageUrl, coverImageUrl and a link preview's webLink.imageUrl) are on cdn-img.blazot.com, a video's videoCover on cdn.blazot.com, and an animated GIF's animatedMedia.url (always https) on cdn-img.blazot.com or a GIF provider's host.

Put sensitive media behind a click

When a transmission's containsSensitiveMedia is true, its author marked its media as sensitive. Hide the media until the viewer chooses to see it, as Blazot does. The text can be shown as usual. A relay's original, in relayedTransmission, has its own containsSensitiveMedia: check it when you show the original's media.

Videos

The API doesn't give a video's file: show its cover (videoCover) and link it to the transmission's url, where the video plays on Blazot, as Concepts describes.

JSON conventions

Every successful response follows the same rules:

  • Names are camelCase: transmissionId, dateTransmitted, containsSensitiveMedia.
  • Every field is sent, even without a value. Text without a value is usually an empty string (""); an object or a time without one is null, as is a poll choice's voteCount until your account has voted or the poll has ended, and a list without items is empty ([]). A transmission's webLink is the exception: it's always there, with every field empty when there's no link, so check webLink.linkUrl. Read a field's description in the API reference to see which it uses.
  • Ids are GUIDs, as strings, such as "3f2c8a51-7d4e-4b9a-9c1e-2a6f0b8d5e17", except an emoticon's categoryId, which is a number.
  • Ignore fields you don't know. New fields can appear at any time: see Versioning.

Error bodies have their own shape: see Errors.

Times

Times are ISO 8601 in UTC, ending in Z: "2026-03-30T17:42:08Z". Most have a fraction of a second, of up to seven digits, such as "2026-03-30T17:42:08.4173621Z", so parse them with a date library rather than by position.

Event start and end times are the exception. An event's dateStart and dateEnd have no Z: "2026-06-14T17:00:00". They're the local time the Site entered, so a race that starts at 5 p.m. starts at 5 p.m. for every viewer. Show them as they are, without converting them to the viewer's time zone. Parse them as a date and time with no zone (DateTime, not DateTimeOffset, in .NET), or just show the string: many date libraries read a time without a zone as the machine's local time and shift it from there. The API doesn't give the event's time zone. dateEnd is null when the event has no end time.

Durations

A poll's duration, how long it stays open, is written as [d.]hh:mm:ss: "1.00:00:00" is one day and "06:30:00" is six and a half hours. The days part is left out when it's zero. When the poll closes is in endTime, a UTC time, so you rarely need to parse the duration.