Merge branch 'develop' into issue/2099
[akkoma] / docs / API / pleroma_api.md
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/blocks_import`
48 ### Imports your blocks.
49 * Method: `POST`
50 * Authentication: required
51 * Params:
52 * `list`: STRING or FILE containing a whitespace-separated list of accounts to block
53 * Response: HTTP 200 on success, 500 on error
54
55 ## `/api/pleroma/mutes_import`
56 ### Imports your mutes.
57 * Method: `POST`
58 * Authentication: required
59 * Params:
60 * `list`: STRING or FILE containing a whitespace-separated list of accounts to mute
61 * Response: HTTP 200 on success, 500 on error
62
63
64 ## `/api/pleroma/captcha`
65 ### Get a new captcha
66 * Method: `GET`
67 * Authentication: not required
68 * Params: none
69 * Response: Provider specific JSON, the only guaranteed parameter is `type`
70 * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint", "seconds_valid": 300}`
71
72 ## `/api/pleroma/delete_account`
73 ### Delete an account
74 * Method `POST`
75 * Authentication: required
76 * Params:
77 * `password`: user's password
78 * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
79 * Example response: `{"error": "Invalid password."}`
80
81 ## `/api/pleroma/disable_account`
82 ### Disable an account
83 * Method `POST`
84 * Authentication: required
85 * Params:
86 * `password`: user's password
87 * Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise
88 * Example response: `{"error": "Invalid password."}`
89
90 ## `/api/pleroma/accounts/mfa`
91 #### Gets current MFA settings
92 * method: `GET`
93 * Authentication: required
94 * OAuth scope: `read:security`
95 * Response: JSON. Returns `{"enabled": "false", "totp": false }`
96
97 ## `/api/pleroma/accounts/mfa/setup/totp`
98 #### Pre-setup the MFA/TOTP method
99 * method: `GET`
100 * Authentication: required
101 * OAuth scope: `write:security`
102 * Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]" }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}`
103
104 ## `/api/pleroma/accounts/mfa/confirm/totp`
105 #### Confirms & enables MFA/TOTP support for user account.
106 * method: `POST`
107 * Authentication: required
108 * OAuth scope: `write:security`
109 * Params:
110 * `password`: user's password
111 * `code`: token from TOTP App
112 * Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
113
114
115 ## `/api/pleroma/accounts/mfa/totp`
116 #### Disables MFA/TOTP method for user account.
117 * method: `DELETE`
118 * Authentication: required
119 * OAuth scope: `write:security`
120 * Params:
121 * `password`: user's password
122 * Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
123 * Example response: `{"error": "Invalid password."}`
124
125 ## `/api/pleroma/accounts/mfa/backup_codes`
126 #### Generstes backup codes MFA for user account.
127 * method: `GET`
128 * Authentication: required
129 * OAuth scope: `write:security`
130 * Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}`
131
132 ## `/api/pleroma/admin/`
133 See [Admin-API](admin_api.md)
134
135 ## `/api/v1/pleroma/notifications/read`
136 ### Mark notifications as read
137 * Method `POST`
138 * Authentication: required
139 * Params (mutually exclusive):
140 * `id`: a single notification id to read
141 * `max_id`: read all notifications up to this id
142 * Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
143
144 ## `/api/v1/pleroma/accounts/:id/subscribe`
145 ### Subscribe to receive notifications for all statuses posted by a user
146 * Method `POST`
147 * Authentication: required
148 * Params:
149 * `id`: account id to subscribe to
150 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
151 * Example response:
152 ```json
153 {
154 "id": "abcdefg",
155 "following": true,
156 "followed_by": false,
157 "blocking": false,
158 "muting": false,
159 "muting_notifications": false,
160 "subscribing": true,
161 "requested": false,
162 "domain_blocking": false,
163 "showing_reblogs": true,
164 "endorsed": false
165 }
166 ```
167
168 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
169 ### Unsubscribe to stop receiving notifications from user statuses
170 * Method `POST`
171 * Authentication: required
172 * Params:
173 * `id`: account id to unsubscribe from
174 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
175 * Example response:
176 ```json
177 {
178 "id": "abcdefg",
179 "following": true,
180 "followed_by": false,
181 "blocking": false,
182 "muting": false,
183 "muting_notifications": false,
184 "subscribing": false,
185 "requested": false,
186 "domain_blocking": false,
187 "showing_reblogs": true,
188 "endorsed": false
189 }
190 ```
191
192 ## `/api/v1/pleroma/accounts/:id/favourites`
193 ### Returns favorites timeline of any user
194 * Method `GET`
195 * Authentication: not required
196 * Params:
197 * `id`: the id of the account for whom to return results
198 * `limit`: optional, the number of records to retrieve
199 * `since_id`: optional, returns results that are more recent than the specified id
200 * `max_id`: optional, returns results that are older than the specified id
201 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
202 * Example response:
203 ```json
204 [
205 {
206 "account": {
207 "id": "9hptFmUF3ztxYh3Svg",
208 "url": "https://pleroma.example.org/users/nick2",
209 "username": "nick2",
210 ...
211 },
212 "application": {"name": "Web", "website": null},
213 "bookmarked": false,
214 "card": null,
215 "content": "This is :moominmamma: note 0",
216 "created_at": "2019-04-15T15:42:15.000Z",
217 "emojis": [],
218 "favourited": false,
219 "favourites_count": 1,
220 "id": "9hptFmVJ02khbzYJaS",
221 "in_reply_to_account_id": null,
222 "in_reply_to_id": null,
223 "language": null,
224 "media_attachments": [],
225 "mentions": [],
226 "muted": false,
227 "pinned": false,
228 "pleroma": {
229 "content": {"text/plain": "This is :moominmamma: note 0"},
230 "conversation_id": 13679,
231 "local": true,
232 "spoiler_text": {"text/plain": "2hu"}
233 },
234 "reblog": null,
235 "reblogged": false,
236 "reblogs_count": 0,
237 "replies_count": 0,
238 "sensitive": false,
239 "spoiler_text": "2hu",
240 "tags": [{"name": "2hu", "url": "/tag/2hu"}],
241 "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
242 "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
243 "visibility": "public"
244 }
245 ]
246 ```
247
248 ## `/api/v1/pleroma/accounts/update_*`
249 ### Set and clear account avatar, banner, and background
250
251 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
252 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
253 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
254
255 ## `/api/v1/pleroma/accounts/confirmation_resend`
256 ### Resend confirmation email
257 * Method `POST`
258 * Params:
259 * `email`: email of that needs to be verified
260 * Authentication: not required
261 * Response: 204 No Content
262
263 ## `/api/v1/pleroma/mascot`
264 ### Gets user mascot image
265 * Method `GET`
266 * Authentication: required
267
268 * Response: JSON. Returns a mastodon media attachment entity.
269 * Example response:
270 ```json
271 {
272 "id": "abcdefg",
273 "url": "https://pleroma.example.org/media/abcdefg.png",
274 "type": "image",
275 "pleroma": {
276 "mime_type": "image/png"
277 }
278 }
279 ```
280
281 ### Updates user mascot image
282 * Method `PUT`
283 * Authentication: required
284 * Params:
285 * `file`: Multipart image
286 * Response: JSON. Returns a mastodon media attachment entity
287 when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
288 * Example response:
289 ```json
290 {
291 "id": "abcdefg",
292 "url": "https://pleroma.example.org/media/abcdefg.png",
293 "type": "image",
294 "pleroma": {
295 "mime_type": "image/png"
296 }
297 }
298 ```
299 * Note: Behaves exactly the same as `POST /api/v1/upload`.
300 Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
301
302 ## `/api/pleroma/notification_settings`
303 ### Updates user notification settings
304 * Method `PUT`
305 * Authentication: required
306 * Params:
307 * `block_from_strangers`: BOOLEAN field, blocks notifications from accounts you do not follow
308 * `hide_notification_contents`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
309 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
310
311 ## `/api/pleroma/healthcheck`
312 ### Healthcheck endpoint with additional system data.
313 * Method `GET`
314 * Authentication: not required
315 * Params: none
316 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
317 * Example response:
318 ```json
319 {
320 "pool_size": 0, # database connection pool
321 "active": 0, # active processes
322 "idle": 0, # idle processes
323 "memory_used": 0.00, # Memory used
324 "healthy": true, # Instance state
325 "job_queue_stats": {} # Job queue stats
326 }
327 ```
328
329 ## `/api/pleroma/change_email`
330 ### Change account email
331 * Method `POST`
332 * Authentication: required
333 * Params:
334 * `password`: user's password
335 * `email`: new email
336 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
337 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
338
339 # Pleroma Conversations
340
341 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
342
343 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
344 2. Pleroma Conversations statuses can be requested by Conversation id.
345 3. Pleroma Conversations can be replied to.
346
347 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.
348
349 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.
350
351 âš  Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`.
352
353 ## `GET /api/v1/pleroma/conversations/:id/statuses`
354 ### Timeline for a given conversation
355 * Method `GET`
356 * Authentication: required
357 * Params: Like other timelines
358 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
359
360 ## `GET /api/v1/pleroma/conversations/:id`
361 ### The conversation with the given ID.
362 * Method `GET`
363 * Authentication: required
364 * Params: None
365 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
366
367 ## `PATCH /api/v1/pleroma/conversations/:id`
368 ### Update a conversation. Used to change the set of recipients.
369 * Method `PATCH`
370 * Authentication: required
371 * Params:
372 * `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.
373 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
374
375 ## `POST /api/v1/pleroma/conversations/read`
376 ### Marks all user's conversations as read.
377 * Method `POST`
378 * Authentication: required
379 * Params: None
380 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
381
382 ## `GET /api/pleroma/emoji/packs/import`
383 ### Imports packs from filesystem
384 * Method `GET`
385 * Authentication: required
386 * Params: None
387 * Response: JSON, returns a list of imported packs.
388
389 ## `GET /api/pleroma/emoji/packs/remote`
390 ### Make request to another instance for packs list
391 * Method `GET`
392 * Authentication: required
393 * Params:
394 * `url`: url of the instance to get packs from
395 * Response: JSON with the pack list, hashmap with pack name and pack contents
396
397 ## `POST /api/pleroma/emoji/packs/download`
398 ### Download pack from another instance
399 * Method `POST`
400 * Authentication: required
401 * Params:
402 * `url`: url of the instance to download from
403 * `name`: pack to download from that instance
404 * `as`: (*optional*) name how to save pack
405 * Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
406 errors downloading the pack
407
408 ## `POST /api/pleroma/emoji/packs/:name`
409 ### Creates an empty pack
410 * Method `POST`
411 * Authentication: required
412 * Params: None
413 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
414
415 ## `PATCH /api/pleroma/emoji/packs/:name`
416 ### Updates (replaces) pack metadata
417 * Method `PATCH`
418 * Authentication: required
419 * Params:
420 * `metadata`: metadata to replace the old one
421 * `license`: Pack license
422 * `homepage`: Pack home page url
423 * `description`: Pack description
424 * `fallback-src`: Fallback url to download pack from
425 * `fallback-src-sha256`: SHA256 encoded for fallback pack archive
426 * `share-files`: is pack allowed for sharing (boolean)
427 * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
428 problem with the new metadata (the error is specified in the "error" part of the response JSON)
429
430 ## `DELETE /api/pleroma/emoji/packs/:name`
431 ### Delete a custom emoji pack
432 * Method `DELETE`
433 * Authentication: required
434 * Params: None
435 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
436
437 ## `POST /api/pleroma/emoji/packs/:name/files`
438 ### Add new file to the pack
439 * Method `POST`
440 * Authentication: required
441 * Params:
442 * `file`: file needs to be uploaded with the multipart request or link to remote file.
443 * `shortcode`: (*optional*) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.
444 * `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename.
445 * Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
446
447 ## `PATCH /api/pleroma/emoji/packs/:name/files`
448 ### Update emoji file from pack
449 * Method `PATCH`
450 * Authentication: required
451 * Params:
452 * `shortcode`: emoji file shortcode
453 * `new_shortcode`: new emoji file shortcode
454 * `new_filename`: new filename for emoji file
455 * `force`: (*optional*) with true value to overwrite existing emoji with new shortcode
456 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
457
458 ## `DELETE /api/pleroma/emoji/packs/:name/files`
459 ### Delete emoji file from pack
460 * Method `DELETE`
461 * Authentication: required
462 * Params:
463 * `shortcode`: emoji file shortcode
464 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
465
466 ## `GET /api/pleroma/emoji/packs`
467
468 ### Lists local custom emoji packs
469
470 * Method `GET`
471 * Authentication: not required
472 * Params:
473 * `page`: page number for packs (default 1)
474 * `page_size`: page size for packs (default 50)
475 * Response: `packs` key with JSON hashmap of pack name to pack contents and `count` key for count of packs.
476
477 ```json
478 {
479 "packs": {
480 "pack_name": {...}, // pack contents
481 ...
482 },
483 "count": 0 // packs count
484 }
485 ```
486
487 ## `GET /api/pleroma/emoji/packs/:name`
488
489 ### Get pack.json for the pack
490
491 * Method `GET`
492 * Authentication: not required
493 * Params:
494 * `page`: page number for files (default 1)
495 * `page_size`: page size for files (default 30)
496 * Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
497
498 ```json
499 {
500 "files": {...},
501 "files_count": 0, // emoji count in pack
502 "pack": {...}
503 }
504 ```
505
506 ## `GET /api/pleroma/emoji/packs/:name/archive`
507 ### Requests a local pack archive from the instance
508 * Method `GET`
509 * Authentication: not required
510 * Params: None
511 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
512 404 if the pack does not exist
513
514 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
515 ### Requests a list of current and recent Listen activities for an account
516 * Method `GET`
517 * Authentication: not required
518 * Params: None
519 * Response: An array of media metadata entities.
520 * Example response:
521 ```json
522 [
523 {
524 "account": {...},
525 "id": "1234",
526 "title": "Some Title",
527 "artist": "Some Artist",
528 "album": "Some Album",
529 "length": 180000,
530 "created_at": "2019-09-28T12:40:45.000Z"
531 }
532 ]
533 ```
534
535 ## `POST /api/v1/pleroma/scrobble`
536 ### Creates a new Listen activity for an account
537 * Method `POST`
538 * Authentication: required
539 * Params:
540 * `title`: the title of the media playing
541 * `album`: the album of the media playing [optional]
542 * `artist`: the artist of the media playing [optional]
543 * `length`: the length of the media playing [optional]
544 * Response: the newly created media metadata entity representing the Listen activity
545
546 # Emoji Reactions
547
548 Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character. To detect the presence of this feature, you can check `pleroma_emoji_reactions` entry in the features list of nodeinfo.
549
550 ## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji`
551 ### React to a post with a unicode emoji
552 * Method: `PUT`
553 * Authentication: required
554 * Params: `emoji`: A single character unicode emoji
555 * Response: JSON, the status.
556
557 ## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji`
558 ### Remove a reaction to a post with a unicode emoji
559 * Method: `DELETE`
560 * Authentication: required
561 * Params: `emoji`: A single character unicode emoji
562 * Response: JSON, the status.
563
564 ## `GET /api/v1/pleroma/statuses/:id/reactions`
565 ### Get an object of emoji to account mappings with accounts that reacted to the post
566 * Method: `GET`
567 * Authentication: optional
568 * Params: None
569 * Response: JSON, a list of emoji/account list tuples, sorted by emoji insertion date, in ascending order, e.g, the first emoji in the list is the oldest.
570 * Example Response:
571 ```json
572 [
573 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
574 {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
575 ]
576 ```
577
578 ## `GET /api/v1/pleroma/statuses/:id/reactions/:emoji`
579 ### Get an object of emoji to account mappings with accounts that reacted to the post for a specific emoji
580 * Method: `GET`
581 * Authentication: optional
582 * Params: None
583 * Response: JSON, a list of emoji/account list tuples
584 * Example Response:
585 ```json
586 [
587 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}
588 ]
589 ```