pleroma_api.md (15114B)
1 # Pleroma API
2
3 Requests that require it can be authenticated with [an OAuth token](https://tools.ietf.org/html/rfc6749), the `_pleroma_key` cookie, or [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).
4
5 Request parameters can be passed via [query strings](https://en.wikipedia.org/wiki/Query_string) or as [form data](https://www.w3.org/TR/html401/interact/forms.html). Files must be uploaded as `multipart/form-data`.
6
7 ## `/api/pleroma/emoji`
8 ### Lists the custom emoji on that server.
9 * Method: `GET`
10 * Authentication: not required
11 * Params: none
12 * Response: JSON
13 * Example response:
14 ```json
15 {
16 "girlpower": {
17 "tags": [
18 "Finmoji"
19 ],
20 "image_url": "/finmoji/128px/girlpower-128.png"
21 },
22 "education": {
23 "tags": [
24 "Finmoji"
25 ],
26 "image_url": "/finmoji/128px/education-128.png"
27 },
28 "finnishlove": {
29 "tags": [
30 "Finmoji"
31 ],
32 "image_url": "/finmoji/128px/finnishlove-128.png"
33 }
34 }
35 ```
36 * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
37
38 ## `/api/pleroma/follow_import`
39 ### Imports your follows, for example from a Mastodon CSV file.
40 * Method: `POST`
41 * Authentication: required
42 * Params:
43 * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow
44 * Response: HTTP 200 on success, 500 on error
45 * Note: Users that can't be followed are silently skipped.
46
47 ## `/api/pleroma/captcha`
48 ### Get a new captcha
49 * Method: `GET`
50 * Authentication: not required
51 * Params: none
52 * Response: Provider specific JSON, the only guaranteed parameter is `type`
53 * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}`
54
55 ## `/api/pleroma/delete_account`
56 ### Delete an account
57 * Method `POST`
58 * Authentication: required
59 * Params:
60 * `password`: user's password
61 * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
62 * Example response: `{"error": "Invalid password."}`
63
64 ## `/api/pleroma/disable_account`
65 ### Disable an account
66 * Method `POST`
67 * Authentication: required
68 * Params:
69 * `password`: user's password
70 * Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise
71 * Example response: `{"error": "Invalid password."}`
72
73 ## `/api/account/register`
74 ### Register a new user
75 * Method `POST`
76 * Authentication: not required
77 * Params:
78 * `nickname`
79 * `fullname`
80 * `bio`
81 * `email`
82 * `password`
83 * `confirm`
84 * `captcha_solution`: optional, contains provider-specific captcha solution,
85 * `captcha_token`: optional, contains provider-specific captcha token
86 * `token`: invite token required when the registrations aren't public.
87 * Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}`
88 * Example response:
89 ```json
90 {
91 "background_image": null,
92 "cover_photo": "https://pleroma.soykaf.com/images/banner.png",
93 "created_at": "Tue Dec 18 16:55:56 +0000 2018",
94 "default_scope": "public",
95 "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.",
96 "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.",
97 "favourites_count": 0,
98 "fields": [],
99 "followers_count": 0,
100 "following": false,
101 "follows_you": false,
102 "friends_count": 0,
103 "id": 6,
104 "is_local": true,
105 "locked": false,
106 "name": "lain",
107 "name_html": "lain",
108 "no_rich_text": false,
109 "pleroma": {
110 "tags": []
111 },
112 "profile_image_url": "https://pleroma.soykaf.com/images/avi.png",
113 "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png",
114 "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png",
115 "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png",
116 "rights": {
117 "delete_others_notice": false
118 },
119 "screen_name": "lain",
120 "statuses_count": 0,
121 "statusnet_blocking": false,
122 "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain"
123 }
124 ```
125
126 ## `/api/pleroma/admin/`…
127 See [Admin-API](Admin-API.md)
128
129 ## `/api/v1/pleroma/notifications/read`
130 ### Mark notifications as read
131 * Method `POST`
132 * Authentication: required
133 * Params (mutually exclusive):
134 * `id`: a single notification id to read
135 * `max_id`: read all notifications up to this id
136 * Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
137
138 ## `/api/v1/pleroma/accounts/:id/subscribe`
139 ### Subscribe to receive notifications for all statuses posted by a user
140 * Method `POST`
141 * Authentication: required
142 * Params:
143 * `id`: account id to subscribe to
144 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
145 * Example response:
146 ```json
147 {
148 "id": "abcdefg",
149 "following": true,
150 "followed_by": false,
151 "blocking": false,
152 "muting": false,
153 "muting_notifications": false,
154 "subscribing": true,
155 "requested": false,
156 "domain_blocking": false,
157 "showing_reblogs": true,
158 "endorsed": false
159 }
160 ```
161
162 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
163 ### Unsubscribe to stop receiving notifications from user statuses
164 * Method `POST`
165 * Authentication: required
166 * Params:
167 * `id`: account id to unsubscribe from
168 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
169 * Example response:
170 ```json
171 {
172 "id": "abcdefg",
173 "following": true,
174 "followed_by": false,
175 "blocking": false,
176 "muting": false,
177 "muting_notifications": false,
178 "subscribing": false,
179 "requested": false,
180 "domain_blocking": false,
181 "showing_reblogs": true,
182 "endorsed": false
183 }
184 ```
185
186 ## `/api/v1/pleroma/accounts/:id/favourites`
187 ### Returns favorites timeline of any user
188 * Method `GET`
189 * Authentication: not required
190 * Params:
191 * `id`: the id of the account for whom to return results
192 * `limit`: optional, the number of records to retrieve
193 * `since_id`: optional, returns results that are more recent than the specified id
194 * `max_id`: optional, returns results that are older than the specified id
195 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
196 * Example response:
197 ```json
198 [
199 {
200 "account": {
201 "id": "9hptFmUF3ztxYh3Svg",
202 "url": "https://pleroma.example.org/users/nick2",
203 "username": "nick2",
204 ...
205 },
206 "application": {"name": "Web", "website": null},
207 "bookmarked": false,
208 "card": null,
209 "content": "This is :moominmamma: note 0",
210 "created_at": "2019-04-15T15:42:15.000Z",
211 "emojis": [],
212 "favourited": false,
213 "favourites_count": 1,
214 "id": "9hptFmVJ02khbzYJaS",
215 "in_reply_to_account_id": null,
216 "in_reply_to_id": null,
217 "language": null,
218 "media_attachments": [],
219 "mentions": [],
220 "muted": false,
221 "pinned": false,
222 "pleroma": {
223 "content": {"text/plain": "This is :moominmamma: note 0"},
224 "conversation_id": 13679,
225 "local": true,
226 "spoiler_text": {"text/plain": "2hu"}
227 },
228 "reblog": null,
229 "reblogged": false,
230 "reblogs_count": 0,
231 "replies_count": 0,
232 "sensitive": false,
233 "spoiler_text": "2hu",
234 "tags": [{"name": "2hu", "url": "/tag/2hu"}],
235 "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
236 "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
237 "visibility": "public"
238 }
239 ]
240 ```
241
242 ## `/api/v1/pleroma/accounts/update_*`
243 ### Set and clear account avatar, banner, and background
244
245 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
246 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
247 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
248
249 ## `/api/v1/pleroma/accounts/confirmation_resend`
250 ### Resend confirmation email
251 * Method `POST`
252 * Params:
253 * `email`: email of that needs to be verified
254 * Authentication: not required
255 * Response: 204 No Content
256
257 ## `/api/v1/pleroma/mascot`
258 ### Gets user mascot image
259 * Method `GET`
260 * Authentication: required
261
262 * Response: JSON. Returns a mastodon media attachment entity.
263 * Example response:
264 ```json
265 {
266 "id": "abcdefg",
267 "url": "https://pleroma.example.org/media/abcdefg.png",
268 "type": "image",
269 "pleroma": {
270 "mime_type": "image/png"
271 }
272 }
273 ```
274
275 ### Updates user mascot image
276 * Method `PUT`
277 * Authentication: required
278 * Params:
279 * `image`: Multipart image
280 * Response: JSON. Returns a mastodon media attachment entity
281 when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
282 * Example response:
283 ```json
284 {
285 "id": "abcdefg",
286 "url": "https://pleroma.example.org/media/abcdefg.png",
287 "type": "image",
288 "pleroma": {
289 "mime_type": "image/png"
290 }
291 }
292 ```
293 * Note: Behaves exactly the same as `POST /api/v1/upload`.
294 Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
295
296 ## `/api/pleroma/notification_settings`
297 ### Updates user notification settings
298 * Method `PUT`
299 * Authentication: required
300 * Params:
301 * `followers`: BOOLEAN field, receives notifications from followers
302 * `follows`: BOOLEAN field, receives notifications from people the user follows
303 * `remote`: BOOLEAN field, receives notifications from people on remote instances
304 * `local`: BOOLEAN field, receives notifications from people on the local instance
305 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
306
307 ## `/api/pleroma/healthcheck`
308 ### Healthcheck endpoint with additional system data.
309 * Method `GET`
310 * Authentication: not required
311 * Params: none
312 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
313 * Example response:
314 ```json
315 {
316 "pool_size": 0, # database connection pool
317 "active": 0, # active processes
318 "idle": 0, # idle processes
319 "memory_used": 0.00, # Memory used
320 "healthy": true # Instance state
321 }
322 ```
323
324 ## `/api/pleroma/change_email`
325 ### Change account email
326 * Method `POST`
327 * Authentication: required
328 * Params:
329 * `password`: user's password
330 * `email`: new email
331 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
332 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
333
334 # Pleroma Conversations
335
336 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
337
338 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
339 2. Pleroma Conversations statuses can be requested by Conversation id.
340 3. Pleroma Conversations can be replied to.
341
342 Conversations have the additional field "recipients" under the "pleroma" key. This holds a list of all the accounts that will receive a message in this conversation.
343
344 The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation.
345
346
347 ## `GET /api/v1/pleroma/conversations/:id/statuses`
348 ### Timeline for a given conversation
349 * Method `GET`
350 * Authentication: required
351 * Params: Like other timelines
352 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
353
354 ## `GET /api/v1/pleroma/conversations/:id`
355 ### The conversation with the given ID.
356 * Method `GET`
357 * Authentication: required
358 * Params: None
359 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
360
361 ## `PATCH /api/v1/pleroma/conversations/:id`
362 ### Update a conversation. Used to change the set of recipients.
363 * Method `PATCH`
364 * Authentication: required
365 * Params:
366 * `recipients`: A list of ids of users that should receive posts to this conversation. This will replace the current list of recipients, so submit the full list. The owner of owner of the conversation will always be part of the set of recipients, though.
367 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
368
369 ## `GET /api/pleroma/emoji/packs`
370 ### Lists the custom emoji packs on the server
371 * Method `GET`
372 * Authentication: not required
373 * Params: None
374 * Response: JSON, "ok" and 200 status and the JSON hashmap of "pack name" to "pack contents"
375
376 ## `PUT /api/pleroma/emoji/packs/:name`
377 ### Creates an empty custom emoji pack
378 * Method `PUT`
379 * Authentication: required
380 * Params: None
381 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
382
383 ## `DELETE /api/pleroma/emoji/packs/:name`
384 ### Delete a custom emoji pack
385 * Method `DELETE`
386 * Authentication: required
387 * Params: None
388 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
389
390 ## `POST /api/pleroma/emoji/packs/:name/update_file`
391 ### Update a file in a custom emoji pack
392 * Method `POST`
393 * Authentication: required
394 * Params:
395 * if the `action` is `add`, adds an emoji named `shortcode` to the pack `pack_name`,
396 that means that the emoji file needs to be uploaded with the request
397 (thus requiring it to be a multipart request) and be named `file`.
398 There can also be an optional `filename` that will be the new emoji file name
399 (if it's not there, the name will be taken from the uploaded file).
400 * if the `action` is `update`, changes emoji shortcode
401 (from `shortcode` to `new_shortcode` or moves the file (from the current filename to `new_filename`)
402 * if the `action` is `remove`, removes the emoji named `shortcode` and it's associated file
403 * Response: JSON, updated "files" section of the pack and 200 status, 409 if the trying to use a shortcode
404 that is already taken, 400 if there was an error with the shortcode, filename or file (additional info
405 in the "error" part of the response JSON)
406
407 ## `POST /api/pleroma/emoji/packs/:name/update_metadata`
408 ### Updates (replaces) pack metadata
409 * Method `POST`
410 * Authentication: required
411 * Params:
412 * `new_data`: new metadata to replace the old one
413 * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
414 problem with the new metadata (the error is specified in the "error" part of the response JSON)
415
416 ## `POST /api/pleroma/emoji/packs/download_from`
417 ### Requests the instance to download the pack from another instance
418 * Method `POST`
419 * Authentication: required
420 * Params:
421 * `instance_address`: the address of the instance to download from
422 * `pack_name`: the pack to download from that instance
423 * Response: JSON, "ok" and 200 status if the pack was downloaded, or 500 if there were
424 errors downloading the pack
425
426 ## `GET /api/pleroma/emoji/packs/:name/download_shared`
427 ### Requests a local pack from the instance
428 * Method `GET`
429 * Authentication: not required
430 * Params: None
431 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
432 404 if the pack does not exist