Skip to content

Entities

  • All IDs are encoded as string representations of integers.
    • IDs can be sorted first by size, and then lexically, to produce a chronological ordering of resources.
  • All datetimes are in ISO 8601 format
  • All HTML strings are sanitized by the server
  • All language codes are in ISO 6391 format

Account

Attribute Type Nullable Added in
id String 0.1.0
username String 0.1.0
acct String 0.1.0
display_name String 0.1.0
locked Boolean 0.1.0
created_at String (Datetime) 0.1.0
followers_count Number 0.1.0
following_count Number 0.1.0
statuses_count Number 0.1.0
note String 0.1.0
url String (URL) 0.1.0
avatar String (URL) 0.1.0
avatar_static String (URL) 1.1.2
header String (URL) 0.1.0
header_static String (URL) 1.1.2
emojis Array of Emoji 2.4.0
moved Account 2.1.0
fields Array of Hash 2.4.0
bot Boolean 2.4.0

Field

Attribute Type Nullable Added in
name String 2.4.0
value String (HTML) 2.4.0
verified_at String (Datetime) 2.6.0

Source

Attribute Type Nullable Added in
privacy String 1.5.0
sensitive Boolean 1.5.0
language String (ISO6391) 2.4.2
note String 1.5.0
fields Array of Hash 2.4.0

Token

Attribute Type Nullable Added in
access_token String 0.1.0
token_type String 0.1.0
scope String 0.1.0
created_at Number 0.1.0

Application

Attribute Type Nullable Added in
name String 0.9.9
website String (URL) 0.9.9

Attachment

Attribute Type Nullable Added in
id String 0.6.0
type String (Enum) 0.6.0
url String (URL) 0.6.0
remote_url String (URL) 0.6.0
preview_url String (URL) 0.6.0
text_url String (URL) 0.6.0
meta Hash 1.5.0
description String 2.0.0

Type

  • unknown
  • image
  • gifv
  • video

Meta

May contain subtrees small and original.

Images may contain width, height, size, aspect, while videos (including GIFV) may contain width, height, frame_rate, duration and bitrate.

There may be another top-level object, focus with the coordinates x and y. These coordinates can be used for smart thumbnail cropping, see this for reference.

Card

Attribute Type Nullable Added in
url String (URL) 1.0.0
title String 1.0.0
description String 1.0.0
image String (URL) 1.0.0
type String (Enum) 1.3.0
author_name String 1.3.0
author_url String (URL) 1.3.0
provider_name String 1.3.0
provider_url String (URL) 1.3.0
html String (HTML) 1.3.0
width Number 1.3.0
height Number 1.3.0

Type

  • link
  • photo
  • video
  • rich

Context

Attribute Type Nullable Added in
ancestors Array of Status 0.6.0
descendants Array of Status 0.6.0

Emoji

Attribute Type Nullable Added in
shortcode String 2.0.0
static_url String (URL) 2.0.0
url String (URL) 2.0.0
visible_in_picker Boolean 2.1.0

Error

The most important part of an error response is the HTTP status code. Standard semantics are followed. The body of an error is a JSON object with this structure:

Attribute Type Nullable Added in
error String 0.6.0

Filter

Attribute Type Nullable Added in
id String 2.4.3
phrase String 2.4.3
context Array of String (Enum) 2.4.3
expires_at String (Datetime) 2.4.3
irreversible Boolean 2.4.3
whole_word Boolean 2.4.3

Context

  • home
  • notifications
  • public
  • thread

Implementation notes

If whole_word is true , client app should do:

  • Define 'word constituent character' for your app. In the official implementation, it's [A-Za-z0-9_] in JavaScript, and [[:word:]] in Ruby. In Ruby case it's the POSIX character class (Letter | Mark | Decimal_Number | Connector_Punctuation).
  • If the phrase starts with a word character, and if the previous character before matched range is a word character, its matched range should be treated to not match.
  • If the phrase ends with a word character, and if the next character after matched range is a word character, its matched range should be treated to not match.

Please check app/javascript/mastodon/selectors/index.js and app/lib/feed_manager.rb in the Soapbox Legacy source code for more details.

Instance

Attribute Type Nullable Added in
uri String 1.1.0
title String 1.1.0
description String 1.1.0
email String 1.1.0
version String 1.3.0
thumbnail String (URL) 1.6.1
urls Hash 1.4.2
stats Hash 1.6.0
languages Array of String (ISO 639, Part 1-5) 2.3.0
contact_account Account 2.3.0

URLs

Attribute Type Nullable Added in
streaming_api String (URL) 1.4.2

Stats

Attribute Type Nullable Added in
user_count Number 1.6.0
status_count Number 1.6.0
domain_count Number 1.6.0

List

Attribute Type Nullable Added in
id String 2.1.0
title String 2.1.0

Mention

Attribute Type Nullable Added in
url String (URL) 0.6.0
username String 0.6.0
acct String 0.6.0
id String 0.6.0

Notification

Attribute Type Nullable Added in
id String 0.9.9
type String (Enum) 0.9.9
created_at String (Datetime) 0.9.9
account Account 0.9.9
status Status 0.9.9

Type

  • follow
  • mention
  • reblog
  • favourite
  • poll

Poll

Attribute Type Nullable Added in
id String 2.8.0
expires_at String (Datetime) 2.8.0
expired Boolean 2.8.0
multiple Boolean 2.8.0
votes_count Number 2.8.0
options Array of Poll option 2.8.0
voted Boolean 2.8.0

Poll option

Attribute Type Nullable Added in
title String 2.8.0
votes_count Number 2.8.0

Push subscription

Attribute Type Nullable Added in
id String 2.4.0
endpoint String (URL) 2.4.0
server_key String 2.4.0
alerts Hash 2.4.0

Alerts

???

Relationship

Attribute Type Nullable Added in
id String 0.6.0
following Boolean 0.6.0
followed_by Boolean 0.6.0
blocking Boolean 0.6.0
muting Boolean 1.1.0
muting_notifications Boolean 2.1.0
requested Boolean 0.9.9
domain_blocking Boolean 1.4.0
showing_reblogs Boolean 2.1.0
endorsed Boolean 2.5.0

Results

Attribute Type Nullable Added in
accounts Array of Account 1.1.0
statuses Array of Status 1.1.0
hashtags Array of Tag 1.1.0

Status

Attribute Type Nullable Added in
id String 0.1.0
uri String 0.1.0
url String (URL) 0.1.0
account Account 0.1.0
in_reply_to_id String 0.1.0
in_reply_to_account_id String 1.0.0
reblog Status 0.1.0
content String (HTML) 0.1.0
created_at String (Datetime) 0.1.0
emojis Array of Emoji 2.0.0
replies_count Number 2.5.0
reblogs_count Number 0.1.0
favourites_count Number 0.1.0
reblogged Boolean 0.1.0
favourited Boolean 0.1.0
muted Boolean 1.4.0
sensitive Boolean 0.9.9
spoiler_text String 1.0.0
visibility String (Enum) 0.9.9
media_attachments Array of Attachment 0.6.0
mentions Array of Mention 0.6.0
tags Array of Tag 0.9.0
card Card 2.6.0
poll Poll 2.8.0
application Application 0.9.9
language String (ISO6391) 1.4.0
pinned Boolean 1.6.0

Visibility

  • public
  • unlisted
  • private
  • direct

ScheduledStatus

Attribute Type Nullable Added in
id String 2.7.0
scheduled_at String (Datetime) 2.7.0
params StatusParams 2.7.0
media_attachments Array of Attachment 2.7.0

StatusParams

Attribute Type Nullable Added in
text String 2.7.0
in_reply_to_id String 2.7.0
media_ids Array of String 2.7.0
sensitive Boolean 2.7.0
spoiler_text String 2.7.0
visibility String (Enum) 2.7.0
scheduled_at String (Datetime) 2.7.0
application_id String 2.7.0

Tag

Attribute Type Nullable Added in
name String 0.9.0
url String (URL) 0.9.0
history Array of History 2.4.1

History

Attribute Type Nullable Added in
day String (UNIX timestamp) 2.4.1
uses Number 2.4.1
accounts Number 2.4.1

Conversation

Attribute Type Nullable Added in
id String 2.6.0
accounts Array of Account 2.6.0
last_status Status 2.6.0
unread Boolean 2.6.0