git.squeep.com Git - akkoma/blob - docs/API/differences_in_mastoapi_responses.md

   1 # Differences in Mastodon API responses from vanilla Mastodon
   2
   3 A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance`
   4
   5 ## Flake IDs
   6
   7 Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mastodon's ids they are sortable strings
   8
   9 ## Attachment cap
  10
  11 Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Pleroma however does not enforce any limits on attachment count neither when returning the status object nor when posting.
  12
  13 ## Timelines
  14
  15 Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users.
  16 Adding the parameter `exclude_visibilities` to the timeline queries will exclude the statuses with the given visibilities. The parameter accepts an array of visibility types (`public`, `unlisted`, `private`, `direct`), e.g., `exclude_visibilities[]=direct&exclude_visibilities[]=private`.
  17
  18 ## Statuses
  19
  20 - `visibility`: has an additional possible value `list`
  21
  22 Has these additional fields under the `pleroma` object:
  23
  24 - `local`: true if the post was made on the local instance
  25 - `conversation_id`: the ID of the AP context the status is associated with (if any)
  26 - `direct_conversation_id`: the ID of the Mastodon direct message conversation the status is associated with (if any)
  27 - `in_reply_to_account_acct`: the `acct` property of User entity for replied user (if any)
  28 - `content`: a map consisting of alternate representations of the `content` property with the key being it's mimetype. Currently the only alternate representation supported is `text/plain`
  29 - `spoiler_text`: a map consisting of alternate representations of the `spoiler_text` property with the key being it's mimetype. Currently the only alternate representation supported is `text/plain`
  30 - `expires_at`: a datetime (iso8601) that states when the post will expire (be deleted automatically), or empty if the post won't expire
  31 - `thread_muted`: true if the thread the post belongs to is muted
  32 - `emoji_reactions`: A list with emoji / reaction maps. The format is {emoji: "☕", count: 1}. Contains no information about the reacting users, for that use the `emoji_reactions_by` endpoint.
  33
  34 ## Attachments
  35
  36 Has these additional fields under the `pleroma` object:
  37
  38 - `mime_type`: mime type of the attachment.
  39
  40 ## Accounts
  41
  42 The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc.
  43
  44 - `/api/v1/accounts/:id`
  45 - `/api/v1/accounts/:id/statuses`
  46
  47 Has these additional fields under the `pleroma` object:
  48
  49 - `tags`: Lists an array of tags for the user
  50 - `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/entities/relationship/
  51 - `is_moderator`: boolean, nullable,  true if user is a moderator
  52 - `is_admin`: boolean, nullable, true if user is an admin
  53 - `confirmation_pending`: boolean, true if a new user account is waiting on email confirmation to be activated
  54 - `hide_followers`: boolean, true when the user has follower hiding enabled
  55 - `hide_follows`: boolean, true when the user has follow hiding enabled
  56 - `hide_followers_count`: boolean, true when the user has follower stat hiding enabled
  57 - `hide_follows_count`: boolean, true when the user has follow stat hiding enabled
  58 - `settings_store`: A generic map of settings for frontends. Opaque to the backend. Only returned in `verify_credentials` and `update_credentials`
  59 - `chat_token`: The token needed for Pleroma chat. Only returned in `verify_credentials`
  60 - `deactivated`: boolean, true when the user is deactivated
  61 - `allow_following_move`: boolean, true when the user allows automatically follow moved following accounts
  62 - `unread_conversation_count`: The count of unread conversations. Only returned to the account owner.
  63
  64 ### Source
  65
  66 Has these additional fields under the `pleroma` object:
  67
  68 - `show_role`: boolean, nullable, true when the user wants his role (e.g admin, moderator) to be shown
  69 - `no_rich_text` - boolean, nullable, true when html tags are stripped from all statuses requested from the API
  70 - `discoverable`: boolean, true when the user allows discovery of the account in search results and other services.
  71 - `actor_type`: string, the type of this account.
  72
  73 ## Conversations
  74
  75 Has an additional field under the `pleroma` object:
  76
  77 - `recipients`: The list of the recipients of this Conversation. These will be addressed when replying to this conversation.
  78
  79 ## GET `/api/v1/conversations`
  80
  81 Accepts additional parameters:
  82
  83 - `recipients`: Only return conversations with the given recipients (a list of user ids). Usage example: `GET /api/v1/conversations?recipients[]=1&recipients[]=2`
  84
  85 ## Account Search
  86
  87 Behavior has changed:
  88
  89 - `/api/v1/accounts/search`: Does not require authentication
  90
  91
  92 ## Notifications
  93
  94 Has these additional fields under the `pleroma` object:
  95
  96 - `is_seen`: true if the notification was read by the user
  97
  98 ### Move Notification
  99
 100 The `type` value is `move`. Has an additional field:
 101
 102 - `target`: new account
 103
 104 ### EmojiReaction Notification
 105
 106 The `type` value is `pleroma:emoji_reaction`. Has these fields:
 107
 108 - `emoji`: The used emoji
 109 - `account`: The account of the user who reacted
 110 - `status`: The status that was reacted on
 111
 112 ## GET `/api/v1/notifications`
 113
 114 Accepts additional parameters:
 115
 116 - `exclude_visibilities`: will exclude the notifications for activities with the given visibilities. The parameter accepts an array of visibility types (`public`, `unlisted`, `private`, `direct`). Usage example: `GET /api/v1/notifications?exclude_visibilities[]=direct&exclude_visibilities[]=private`.
 117 - `with_move`: boolean, when set to `true` will include Move notifications. `false` by default.
 118
 119 ## POST `/api/v1/statuses`
 120
 121 Additional parameters can be added to the JSON body/Form data:
 122
 123 - `preview`: boolean, if set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example.
 124 - `content_type`: string, contain the MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint.
 125 - `to`: A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply.
 126 - `visibility`: string, besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`.
 127 - `expires_in`: The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour.
 128 - `in_reply_to_conversation_id`: Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`.
 129
 130 ## GET `/api/v1/statuses`
 131
 132 An endpoint to get multiple statuses by IDs.
 133
 134 Required parameters:
 135
 136 - `ids`: array of activity ids
 137
 138 Usage example: `GET /api/v1/statuses/?ids[]=1&ids[]=2`.
 139
 140 Returns: array of Status.
 141
 142 The maximum number of statuses is limited to 100 per request.
 143
 144 ## PATCH `/api/v1/update_credentials`
 145
 146 Additional parameters can be added to the JSON body/Form data:
 147
 148 - `no_rich_text` - if true, html tags are stripped from all statuses requested from the API
 149 - `hide_followers` - if true, user's followers will be hidden
 150 - `hide_follows` - if true, user's follows will be hidden
 151 - `hide_followers_count` - if true, user's follower count will be hidden
 152 - `hide_follows_count` - if true, user's follow count will be hidden
 153 - `hide_favorites` - if true, user's favorites timeline will be hidden
 154 - `show_role` - if true, user's role (e.g admin, moderator) will be exposed to anyone in the API
 155 - `default_scope` - the scope returned under `privacy` key in Source subentity
 156 - `pleroma_settings_store` - Opaque user settings to be saved on the backend.
 157 - `skip_thread_containment` - if true, skip filtering out broken threads
 158 - `allow_following_move` - if true, allows automatically follow moved following accounts
 159 - `pleroma_background_image` - sets the background image of the user.
 160 - `discoverable` - if true, discovery of this account in search results and other services is allowed.
 161 - `actor_type` - the type of this account.
 162
 163 ### Pleroma Settings Store
 164 Pleroma has mechanism that allows frontends to save blobs of json for each user on the backend. This can be used to save frontend-specific settings for a user that the backend does not need to know about.
 165
 166 The parameter should have a form of `{frontend_name: {...}}`, with `frontend_name` identifying your type of client, e.g. `pleroma_fe`. It will overwrite everything under this property, but will not overwrite other frontend's settings.
 167
 168 This information is returned in the `verify_credentials` endpoint.
 169
 170 ## Authentication
 171
 172 *Pleroma supports refreshing tokens.
 173
 174 `POST /oauth/token`
 175 Post here request with grant_type=refresh_token to obtain new access token. Returns an access token.
 176
 177 ## Account Registration
 178 `POST /api/v1/accounts`
 179
 180 Has theses additionnal parameters (which are the same as in Pleroma-API):
 181     * `fullname`: optional
 182     * `bio`: optional
 183     * `captcha_solution`: optional, contains provider-specific captcha solution,
 184     * `captcha_token`: optional, contains provider-specific captcha token
 185     * `token`: invite token required when the registerations aren't public.
 186
 187 ## Markers
 188
 189 Has these additional fields under the `pleroma` object:
 190
 191 - `unread_count`: contains number unread notifications