be3c802af23d675d9abb5ec81c55da2d41a1b20f
[akkoma] / 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 lexically sortable strings
8
9 ## Timelines
10
11 Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users.
12 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`.
13 Adding the parameter `reply_visibility` to the public and home timelines queries will filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you.
14
15 ## Statuses
16
17 - `visibility`: has an additional possible value `list`
18
19 Has these additional fields under the `pleroma` object:
20
21 - `local`: true if the post was made on the local instance
22 - `conversation_id`: the ID of the AP context the status is associated with (if any)
23 - `direct_conversation_id`: the ID of the Mastodon direct message conversation the status is associated with (if any)
24 - `in_reply_to_account_acct`: the `acct` property of User entity for replied user (if any)
25 - `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`
26 - `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`
27 - `expires_at`: a datetime (iso8601) that states when the post will expire (be deleted automatically), or empty if the post won't expire
28 - `thread_muted`: true if the thread the post belongs to is muted
29 - `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint.
30
31 ## Media Attachments
32
33 Has these additional fields under the `pleroma` object:
34
35 - `mime_type`: mime type of the attachment.
36
37 ### Attachment cap
38
39 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.
40
41 ### Limitations
42
43 Pleroma does not process remote images and therefore cannot include fields such as `meta` and `blurhash`. It does not support focal points or aspect ratios. The frontend is expected to handle it.
44
45 ## Accounts
46
47 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.
48
49 - `/api/v1/accounts/:id`
50 - `/api/v1/accounts/:id/statuses`
51
52 Has these additional fields under the `pleroma` object:
53
54 - `tags`: Lists an array of tags for the user
55 - `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/entities/relationship/
56 - `is_moderator`: boolean, nullable, true if user is a moderator
57 - `is_admin`: boolean, nullable, true if user is an admin
58 - `confirmation_pending`: boolean, true if a new user account is waiting on email confirmation to be activated
59 - `hide_followers`: boolean, true when the user has follower hiding enabled
60 - `hide_follows`: boolean, true when the user has follow hiding enabled
61 - `hide_followers_count`: boolean, true when the user has follower stat hiding enabled
62 - `hide_follows_count`: boolean, true when the user has follow stat hiding enabled
63 - `settings_store`: A generic map of settings for frontends. Opaque to the backend. Only returned in `verify_credentials` and `update_credentials`
64 - `chat_token`: The token needed for Pleroma chat. Only returned in `verify_credentials`
65 - `deactivated`: boolean, true when the user is deactivated
66 - `allow_following_move`: boolean, true when the user allows automatically follow moved following accounts
67 - `unread_conversation_count`: The count of unread conversations. Only returned to the account owner.
68 - `unread_notifications_count`: The count of unread notifications. Only returned to the account owner.
69
70 ### Source
71
72 Has these additional fields under the `pleroma` object:
73
74 - `show_role`: boolean, nullable, true when the user wants his role (e.g admin, moderator) to be shown
75 - `no_rich_text` - boolean, nullable, true when html tags are stripped from all statuses requested from the API
76 - `discoverable`: boolean, true when the user allows discovery of the account in search results and other services.
77 - `actor_type`: string, the type of this account.
78
79 ## Conversations
80
81 Has an additional field under the `pleroma` object:
82
83 - `recipients`: The list of the recipients of this Conversation. These will be addressed when replying to this conversation.
84
85 ## GET `/api/v1/conversations`
86
87 Accepts additional parameters:
88
89 - `recipients`: Only return conversations with the given recipients (a list of user ids). Usage example: `GET /api/v1/conversations?recipients[]=1&recipients[]=2`
90
91 ## Account Search
92
93 Behavior has changed:
94
95 - `/api/v1/accounts/search`: Does not require authentication
96
97 ## Search (global)
98
99 Unlisted posts are available in search results, they are considered to be public posts that shouldn't be shown in local/federated timeline.
100
101 ## Notifications
102
103 Has these additional fields under the `pleroma` object:
104
105 - `is_seen`: true if the notification was read by the user
106
107 ### Move Notification
108
109 The `type` value is `move`. Has an additional field:
110
111 - `target`: new account
112
113 ### EmojiReact Notification
114
115 The `type` value is `pleroma:emoji_reaction`. Has these fields:
116
117 - `emoji`: The used emoji
118 - `account`: The account of the user who reacted
119 - `status`: The status that was reacted on
120
121 ## GET `/api/v1/notifications`
122
123 Accepts additional parameters:
124
125 - `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`.
126 - `include_types`: will include the notifications for activities with the given types. The parameter accepts an array of types (`mention`, `follow`, `reblog`, `favourite`, `move`, `pleroma:emoji_reaction`). Usage example: `GET /api/v1/notifications?include_types[]=mention&include_types[]=reblog`.
127
128 ## DELETE `/api/v1/notifications/destroy_multiple`
129
130 An endpoint to delete multiple statuses by IDs.
131
132 Required parameters:
133
134 - `ids`: array of activity ids
135
136 Usage example: `DELETE /api/v1/notifications/destroy_multiple/?ids[]=1&ids[]=2`.
137
138 Returns on success: 200 OK `{}`
139
140 ## POST `/api/v1/statuses`
141
142 Additional parameters can be added to the JSON body/Form data:
143
144 - `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.
145 - `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.
146 - `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.
147 - `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`.
148 - `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.
149 - `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`.
150
151 ## GET `/api/v1/statuses`
152
153 An endpoint to get multiple statuses by IDs.
154
155 Required parameters:
156
157 - `ids`: array of activity ids
158
159 Usage example: `GET /api/v1/statuses/?ids[]=1&ids[]=2`.
160
161 Returns: array of Status.
162
163 The maximum number of statuses is limited to 100 per request.
164
165 ## PATCH `/api/v1/update_credentials`
166
167 Additional parameters can be added to the JSON body/Form data:
168
169 - `no_rich_text` - if true, html tags are stripped from all statuses requested from the API
170 - `hide_followers` - if true, user's followers will be hidden
171 - `hide_follows` - if true, user's follows will be hidden
172 - `hide_followers_count` - if true, user's follower count will be hidden
173 - `hide_follows_count` - if true, user's follow count will be hidden
174 - `hide_favorites` - if true, user's favorites timeline will be hidden
175 - `show_role` - if true, user's role (e.g admin, moderator) will be exposed to anyone in the API
176 - `default_scope` - the scope returned under `privacy` key in Source subentity
177 - `pleroma_settings_store` - Opaque user settings to be saved on the backend.
178 - `skip_thread_containment` - if true, skip filtering out broken threads
179 - `allow_following_move` - if true, allows automatically follow moved following accounts
180 - `pleroma_background_image` - sets the background image of the user.
181 - `discoverable` - if true, discovery of this account in search results and other services is allowed.
182 - `actor_type` - the type of this account.
183
184 ### Pleroma Settings Store
185
186 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.
187
188 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.
189
190 This information is returned in the `verify_credentials` endpoint.
191
192 ## Authentication
193
194 *Pleroma supports refreshing tokens.*
195
196 `POST /oauth/token`
197
198 Post here request with `grant_type=refresh_token` to obtain new access token. Returns an access token.
199
200 ## Account Registration
201
202 `POST /api/v1/accounts`
203
204 Has theses additional parameters (which are the same as in Pleroma-API):
205
206 - `fullname`: optional
207 - `bio`: optional
208 - `captcha_solution`: optional, contains provider-specific captcha solution,
209 - `captcha_token`: optional, contains provider-specific captcha token
210 - `captcha_answer_data`: optional, contains provider-specific captcha data
211 - `token`: invite token required when the registrations aren't public.
212
213 ## Instance
214
215 `GET /api/v1/instance` has additional fields
216
217 - `max_toot_chars`: The maximum characters per post
218 - `poll_limits`: The limits of polls
219 - `upload_limit`: The maximum upload file size
220 - `avatar_upload_limit`: The same for avatars
221 - `background_upload_limit`: The same for backgrounds
222 - `banner_upload_limit`: The same for banners
223 - `background_image`: A background image that frontends can use
224 - `pleroma.metadata.features`: A list of supported features
225 - `pleroma.metadata.federation`: The federation restrictions of this instance
226 - `vapid_public_key`: The public key needed for push messages
227
228 ## Markers
229
230 Has these additional fields under the `pleroma` object:
231
232 - `unread_count`: contains number unread notifications
233
234 ## Streaming
235
236 There is an additional `user:pleroma_chat` stream. Incoming chat messages will make the current chat be sent to this `user` stream. The `event` of an incoming chat message is `pleroma:chat_update`. The payload is the updated chat with the incoming chat message in the `last_message` field.