total rebase
[anni] / docs / development / 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 The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/api/pleroma/*` will be deprecated in the future).
8
9 ## `/api/v1/pleroma/emoji`
10 ### Lists the custom emoji on that server.
11 * Method: `GET`
12 * Authentication: not required
13 * Params: none
14 * Response: JSON
15 * Example response:
16 ```json
17 {
18   "girlpower": {
19     "tags": [
20       "Finmoji"
21     ],
22     "image_url": "/finmoji/128px/girlpower-128.png"
23   },
24   "education": {
25     "tags": [
26       "Finmoji"
27     ],
28     "image_url": "/finmoji/128px/education-128.png"
29   },
30   "finnishlove": {
31     "tags": [
32       "Finmoji"
33     ],
34     "image_url": "/finmoji/128px/finnishlove-128.png"
35   }
36 }
37 ```
38 * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
39
40 ## `/api/pleroma/follow_import`
41 ### Imports your follows, for example from a Mastodon CSV file.
42 * Method: `POST`
43 * Authentication: required
44 * Params:
45     * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow
46 * Response: HTTP 200 on success, 500 on error
47 * Note: Users that can't be followed are silently skipped.
48
49 ## `/api/pleroma/blocks_import`
50 ### Imports your blocks.
51 * Method: `POST`
52 * Authentication: required
53 * Params:
54     * `list`: STRING or FILE containing a whitespace-separated list of accounts to block
55 * Response: HTTP 200 on success, 500 on error
56
57 ## `/api/pleroma/mutes_import`
58 ### Imports your mutes.
59 * Method: `POST`
60 * Authentication: required
61 * Params:
62     * `list`: STRING or FILE containing a whitespace-separated list of accounts to mute
63 * Response: HTTP 200 on success, 500 on error
64
65 ## `/api/v1/pleroma/captcha`
66 ### Get a new captcha
67 * Method: `GET`
68 * Authentication: not required
69 * Params: none
70 * Response: Provider specific JSON, the only guaranteed parameter is `type`
71 * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint", "seconds_valid": 300}`
72
73 ## `/api/pleroma/delete_account`
74 ### Delete an account
75 * Method `POST`
76 * Authentication: required
77 * Params:
78     * `password`: user's password
79 * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
80 * Example response: `{"error": "Invalid password."}`
81
82 ## `/api/pleroma/disable_account`
83 ### Disable an account
84 * Method `POST`
85 * Authentication: required
86 * Params:
87     * `password`: user's password
88 * Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise
89 * Example response: `{"error": "Invalid password."}`
90
91 ## `/api/pleroma/accounts/mfa`
92 #### Gets current MFA settings
93 * method: `GET`
94 * Authentication: required
95 * OAuth scope: `read:security`
96 * Response: JSON. Returns `{"settings": {"enabled": "false", "totp": false }}`
97 * Note: `enabled` is whether multi-factor auth is enabled for the user in general, while `totp` is one type of MFA.
98
99 ## `/api/pleroma/accounts/mfa/setup/totp`
100 #### Pre-setup the MFA/TOTP method
101 * method: `GET`
102 * Authentication: required
103 * OAuth scope: `write:security`
104 * Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]"  }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}`
105
106 ## `/api/pleroma/accounts/mfa/confirm/totp`
107 #### Confirms & enables MFA/TOTP support for user account.
108 * method: `POST`
109 * Authentication: required
110 * OAuth scope: `write:security`
111 * Params:
112     * `password`: user's password
113     * `code`: token from TOTP App
114 * Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
115
116
117 ## `/api/pleroma/accounts/mfa/totp`
118 ####  Disables MFA/TOTP method for user account.
119 * method: `DELETE`
120 * Authentication: required
121 * OAuth scope: `write:security`
122 * Params:
123     * `password`: user's password
124 * Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
125 * Example response: `{"error": "Invalid password."}`
126
127 ## `/api/pleroma/accounts/mfa/backup_codes`
128 ####  Generstes backup codes MFA for user account.
129 * method: `GET`
130 * Authentication: required
131 * OAuth scope: `write:security`
132 * Response: JSON. Returns `{"codes": codes}` when successful, otherwise HTTP 422 `{"error": "[error message]"}`
133
134 ## `/api/v1/pleroma/admin/`
135 See [Admin-API](admin_api.md)
136
137 ## `/api/v1/pleroma/notifications/read`
138 ### Mark notifications as read
139 * Method `POST`
140 * Authentication: required
141 * Params (mutually exclusive):
142     * `id`: a single notification id to read
143     * `max_id`: read all notifications up to this id
144 * Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
145
146 ## `/api/v1/pleroma/accounts/:id/subscribe`
147 ### Subscribe to receive notifications for all statuses posted by a user
148 * Method `POST`
149 * Authentication: required
150 * Params:
151     * `id`: account id to subscribe to
152 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
153 * Example response:
154 ```json
155 {
156   "id": "abcdefg",
157   "following": true,
158   "followed_by": false,
159   "blocking": false,
160   "muting": false,
161   "muting_notifications": false,
162   "subscribing": true,
163   "notifying": true,
164   "requested": false,
165   "domain_blocking": false,
166   "showing_reblogs": true,
167   "endorsed": false,
168   "note": ""
169 }
170 ```
171
172 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
173 ### Unsubscribe to stop receiving notifications from user statuses
174 * Method `POST`
175 * Authentication: required
176 * Params:
177     * `id`: account id to unsubscribe from
178 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
179 * Example response:
180 ```json
181 {
182   "id": "abcdefg",
183   "following": true,
184   "followed_by": false,
185   "blocking": false,
186   "muting": false,
187   "muting_notifications": false,
188   "subscribing": false,
189   "notifying": false,
190   "requested": false,
191   "domain_blocking": false,
192   "showing_reblogs": true,
193   "endorsed": false,
194   "note": ""
195 }
196 ```
197
198 ## `/api/v1/pleroma/accounts/:id/favourites`
199 ### Returns favorites timeline of any user
200 * Method `GET`
201 * Authentication: not required
202 * Params:
203     * `id`: the id of the account for whom to return results
204     * `limit`: optional, the number of records to retrieve
205     * `since_id`: optional, returns results that are more recent than the specified id
206     * `max_id`: optional, returns results that are older than the specified id
207 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
208 * Example response:
209 ```json
210 [
211   {
212     "account": {
213       "id": "9hptFmUF3ztxYh3Svg",
214       "url": "https://pleroma.example.org/users/nick2",
215       "username": "nick2",
216       ...
217     },
218     "application": {"name": "Web", "website": null},
219     "bookmarked": false,
220     "card": null,
221     "content": "This is :moominmamma: note 0",
222     "created_at": "2019-04-15T15:42:15.000Z",
223     "emojis": [],
224     "favourited": false,
225     "favourites_count": 1,
226     "id": "9hptFmVJ02khbzYJaS",
227     "in_reply_to_account_id": null,
228     "in_reply_to_id": null,
229     "language": null,
230     "media_attachments": [],
231     "mentions": [],
232     "muted": false,
233     "pinned": false,
234     "pleroma": {
235       "content": {"text/plain": "This is :moominmamma: note 0"},
236       "conversation_id": 13679,
237       "local": true,
238       "spoiler_text": {"text/plain": "2hu"}
239     },
240     "reblog": null,
241     "reblogged": false,
242     "reblogs_count": 0,
243     "replies_count": 0,
244     "sensitive": false,
245     "spoiler_text": "2hu",
246     "tags": [{"name": "2hu", "url": "/tag/2hu"}],
247     "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
248     "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
249     "visibility": "public"
250   }
251 ]
252 ```
253
254
255 ## `/api/v1/pleroma/accounts/:id/endorsements`
256 ### Returns users endorsed by a user
257 * Method `GET`
258 * Authentication: not required
259 * Params:
260     * `id`: the id of the account for whom to return results
261 * Response: JSON, returns a list of Mastodon Account entities
262
263 ## `/api/v1/pleroma/accounts/update_*`
264 ### Set and clear account avatar, banner, and background
265
266 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
267 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
268 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
269
270 ## `/api/v1/pleroma/accounts/confirmation_resend`
271 ### Resend confirmation email
272 * Method `POST`
273 * Params:
274     * `email`: email of that needs to be verified
275 * Authentication: not required
276 * Response: 204 No Content
277
278 ## `/api/v1/pleroma/statuses/:id/quotes`
279 ### Gets quotes for a given status
280 * Method `GET`
281 * Authentication: not required
282 * Params:
283     * `id`: the id of the status
284 * Response: JSON, returns a list of Mastodon Status entities
285
286 ## `GET /api/v1/pleroma/bookmark_folders`
287 ### Gets user bookmark folders
288 * Authentication: required
289
290 * Response: JSON. Returns a list of bookmark folders.
291 * Example response:
292 ```json
293 [
294     {
295         "id": "9umDrYheeY451cQnEe",
296         "name": "Read later",
297         "emoji": "🕓",
298         "source": {
299           "emoji": "🕓"
300         }
301     }
302 ]
303 ```
304
305 ## `POST /api/v1/pleroma/bookmark_folders`
306 ### Creates a bookmark folder
307 * Authentication: required
308
309 * Params:
310     * `name`: folder name
311     * `emoji`: folder emoji (optional)
312 * Response: JSON. Returns a single bookmark folder.
313
314 ## `PATCH /api/v1/pleroma/bookmark_folders/:id`
315 ### Updates a bookmark folder
316 * Authentication: required
317
318 * Params:
319     * `id`: folder id
320     * `name`: folder name (optional)
321     * `emoji`: folder emoji (optional)
322 * Response: JSON. Returns a single bookmark folder.
323
324 ## `DELETE /api/v1/pleroma/bookmark_folders/:id`
325 ### Deletes a bookmark folder
326 * Authentication: required
327
328 * Params:
329     * `id`: folder id
330 * Response: JSON. Returns a single bookmark folder.
331
332 ## `/api/v1/pleroma/mascot`
333 ### Gets user mascot image
334 * Method `GET`
335 * Authentication: required
336
337 * Response: JSON. Returns a mastodon media attachment entity.
338 * Example response:
339 ```json
340 {
341     "id": "abcdefg",
342     "url": "https://pleroma.example.org/media/abcdefg.png",
343     "type": "image",
344     "pleroma": {
345         "mime_type": "image/png"
346     }
347 }
348 ```
349
350 ### Updates user mascot image
351 * Method `PUT`
352 * Authentication: required
353 * Params:
354     * `file`: Multipart image
355 * Response: JSON. Returns a mastodon media attachment entity
356   when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
357 * Example response:
358 ```json
359 {
360     "id": "abcdefg",
361     "url": "https://pleroma.example.org/media/abcdefg.png",
362     "type": "image",
363     "pleroma": {
364         "mime_type": "image/png"
365     }
366 }
367 ```
368 * Note: Behaves exactly the same as `POST /api/v1/upload`.
369   Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
370
371 ## `/api/pleroma/notification_settings`
372 ### Updates user notification settings
373 * Method `PUT`
374 * Authentication: required
375 * Params:
376     * `block_from_strangers`: BOOLEAN field, blocks notifications from accounts you do not follow
377     * `hide_notification_contents`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
378 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
379
380 ## `/api/v1/pleroma/healthcheck`
381 ### Healthcheck endpoint with additional system data.
382 * Method `GET`
383 * Authentication: not required
384 * Params: none
385 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
386 * Example response:
387 ```json
388 {
389   "pool_size": 0, # database connection pool
390   "active": 0, # active processes
391   "idle": 0, # idle processes
392   "memory_used": 0.00, # Memory used
393   "healthy": true, # Instance state
394   "job_queue_stats": {} # Job queue stats
395 }
396 ```
397
398 ## `/api/pleroma/change_email`
399 ### Change account email
400 * Method `POST`
401 * Authentication: required
402 * Params:
403     * `password`: user's password
404     * `email`: new email
405 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
406 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
407
408 ## `/api/pleroma/move_account`
409 ### Move account
410 * Method `POST`
411 * Authentication: required
412 * Params:
413     * `password`: user's password
414     * `target_account`: the nickname of the target account (e.g. `foo@example.org`)
415 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
416 * Note: This endpoint emits a `Move` activity to all followers of the current account. Some remote servers will automatically unfollow the current account and follow the target account upon seeing this, but this depends on the remote server implementation and cannot be guaranteed. For local followers , they will automatically unfollow and follow if and only if they have set the `allow_following_move` preference ("Allow auto-follow when following account moves").
417
418 ## `/api/pleroma/aliases`
419 ### Get aliases of the current account
420 * Method `GET`
421 * Authentication: required
422 * Response: JSON. Returns `{"aliases": [alias, ...]}`, where `alias` is the nickname of an alias, e.g. `foo@example.org`.
423
424 ### Add alias to the current account
425 * Method `PUT`
426 * Authentication: required
427 * Params:
428     * `alias`: the nickname of the alias to add, e.g. `foo@example.org`.
429 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
430
431 ### Delete alias from the current account
432 * Method `DELETE`
433 * Authentication: required
434 * Params:
435     * `alias`: the nickname of the alias to delete, e.g. `foo@example.org`.
436 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
437
438 ## `/api/v1/pleroma/remote_interaction`
439 ## Interact with profile or status from remote account
440 * Metod `POST`
441 * Authentication: not required
442 * Params:
443     * `ap_id`: Profile or status ActivityPub ID
444     * `profile`: Remote profile webfinger
445 * Response: JSON. Returns `{"url": "[redirect url]"}` on success, `{"error": "[error message]"}` otherwise
446
447 # Pleroma Conversations
448
449 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
450
451 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
452 2. Pleroma Conversations statuses can be requested by Conversation id.
453 3. Pleroma Conversations can be replied to.
454
455 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.
456
457 The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visibility to direct and address only the people who are the recipients of that Conversation.
458
459 âš  Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`.
460
461 ## `GET /api/v1/pleroma/conversations/:id/statuses`
462 ### Timeline for a given conversation
463 * Method `GET`
464 * Authentication: required
465 * Params: Like other timelines
466 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
467
468 ## `GET /api/v1/pleroma/conversations/:id`
469 ### The conversation with the given ID.
470 * Method `GET`
471 * Authentication: required
472 * Params: None
473 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
474
475 ## `PATCH /api/v1/pleroma/conversations/:id`
476 ### Update a conversation. Used to change the set of recipients.
477 * Method `PATCH`
478 * Authentication: required
479 * Params:
480     * `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.
481 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
482
483 ## `POST /api/v1/pleroma/conversations/read`
484 ### Marks all user's conversations as read.
485 * Method `POST`
486 * Authentication: required
487 * Params: None
488 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
489
490 ## `GET /api/v1/pleroma/emoji/pack?name=:name`
491
492 ### Get pack.json for the pack
493
494 * Method `GET`
495 * Authentication: not required
496 * Params:
497   * `page`: page number for files (default 1)
498   * `page_size`: page size for files (default 30)
499 * Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
500
501 ```json
502 {
503   "files": {...},
504   "files_count": 0, // emoji count in pack
505   "pack": {...}
506 }
507 ```
508
509 ## `POST /api/v1/pleroma/emoji/pack?name=:name`
510
511 ### Creates an empty pack
512
513 * Method `POST`
514 * Authentication: required (admin)
515 * Params:
516   * `name`: pack name
517 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
518
519 ## `PATCH /api/v1/pleroma/emoji/pack?name=:name`
520
521 ### Updates (replaces) pack metadata
522
523 * Method `PATCH`
524 * Authentication: required (admin)
525 * Params:
526   * `name`: pack name
527   * `metadata`: metadata to replace the old one
528     * `license`: Pack license
529     * `homepage`: Pack home page url
530     * `description`: Pack description
531     * `fallback-src`: Fallback url to download pack from
532     * `fallback-src-sha256`: SHA256 encoded for fallback pack archive
533     * `share-files`: is pack allowed for sharing (boolean)
534 * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
535   problem with the new metadata (the error is specified in the "error" part of the response JSON)
536
537 ## `DELETE /api/v1/pleroma/emoji/pack?name=:name`
538
539 ### Delete a custom emoji pack
540
541 * Method `DELETE`
542 * Authentication: required (admin)
543 * Params:
544   * `name`: pack name
545 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
546
547 ## `GET /api/v1/pleroma/emoji/packs/import`
548
549 ### Imports packs from filesystem
550
551 * Method `GET`
552 * Authentication: required (admin)
553 * Params: None
554 * Response: JSON, returns a list of imported packs.
555
556 ## `GET /api/v1/pleroma/emoji/packs/remote`
557
558 ### Make request to another instance for packs list
559
560 * Method `GET`
561 * Authentication: required (admin)
562 * Params:
563   * `url`: url of the instance to get packs from
564   * `page`: page number for packs (default 1)
565   * `page_size`: page size for packs (default 50)
566 * Response: JSON with the pack list, hashmap with pack name and pack contents
567
568 ## `POST /api/v1/pleroma/emoji/packs/download`
569
570 ### Download pack from another instance
571
572 * Method `POST`
573 * Authentication: required (admin)
574 * Params:
575   * `url`: url of the instance to download from
576   * `name`: pack to download from that instance
577   * `as`: (*optional*) name how to save pack
578 * Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
579   errors downloading the pack
580
581 ## `POST /api/v1/pleroma/emoji/packs/files?name=:name`
582
583 ### Add new file to the pack
584
585 * Method `POST`
586 * Authentication: required (admin)
587 * Params:
588   * `name`: pack name
589   * `file`: file needs to be uploaded with the multipart request or link to remote file.
590   * `shortcode`: (*optional*) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.
591   * `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename.
592 * Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
593
594 ## `PATCH /api/v1/pleroma/emoji/packs/files?name=:name`
595
596 ### Update emoji file from pack
597
598 * Method `PATCH`
599 * Authentication: required (admin)
600 * Params:
601   * `name`: pack name
602   * `shortcode`: emoji file shortcode
603   * `new_shortcode`: new emoji file shortcode
604   * `new_filename`: new filename for emoji file
605   * `force`: (*optional*) with true value to overwrite existing emoji with new shortcode
606 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
607
608 ## `DELETE /api/v1/pleroma/emoji/packs/files?name=:name`
609
610 ### Delete emoji file from pack
611
612 * Method `DELETE`
613 * Authentication: required (admin)
614 * Params:
615   * `name`: pack name
616   * `shortcode`: emoji file shortcode
617 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
618
619 ## `GET /api/v1/pleroma/emoji/packs`
620
621 ### Lists local custom emoji packs
622
623 * Method `GET`
624 * Authentication: not required
625 * Params:
626   * `page`: page number for packs (default 1)
627   * `page_size`: page size for packs (default 50)
628 * Response: `packs` key with JSON hashmap of pack name to pack contents and `count` key for count of packs.
629
630 ```json
631 {
632   "packs": {
633     "pack_name": {...}, // pack contents
634     ...
635   },
636   "count": 0 // packs count
637 }
638 ```
639
640 ## `GET /api/v1/pleroma/emoji/packs/archive?name=:name`
641
642 ### Requests a local pack archive from the instance
643
644 * Method `GET`
645 * Authentication: not required
646 * Params:
647   * `name`: pack name
648 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
649   404 if the pack does not exist
650
651 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
652
653 Audio scrobbling in Pleroma is **deprecated**.
654
655 ### Requests a list of current and recent Listen activities for an account
656 * Method `GET`
657 * Authentication: not required
658 * Params: None
659 * Response: An array of media metadata entities.
660 * Example response:
661 ```json
662 [
663    {
664        "account": {...},
665        "id": "1234",
666        "title": "Some Title",
667        "artist": "Some Artist",
668        "album": "Some Album",
669        "length": 180000,
670        "created_at": "2019-09-28T12:40:45.000Z"
671    }
672 ]
673 ```
674
675 ## `POST /api/v1/pleroma/scrobble`
676
677 Audio scrobbling in Pleroma is **deprecated**.
678
679 ### Creates a new Listen activity for an account
680 * Method `POST`
681 * Authentication: required
682 * Params:
683   * `title`: the title of the media playing
684   * `album`: the album of the media playing [optional]
685   * `artist`: the artist of the media playing [optional]
686   * `length`: the length of the media playing [optional]
687 * Response: the newly created media metadata entity representing the Listen activity
688
689 # Emoji Reactions
690
691 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.
692
693 ## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji`
694 ### React to a post with a unicode emoji
695 * Method: `PUT`
696 * Authentication: required
697 * Params: `emoji`: A unicode RGI emoji or a regional indicator
698 * Response: JSON, the status.
699
700 ## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji`
701 ### Remove a reaction to a post with a unicode emoji
702 * Method: `DELETE`
703 * Authentication: required
704 * Params: `emoji`: A unicode RGI emoji or a regional indicator
705 * Response: JSON, the status.
706
707 ## `GET /api/v1/pleroma/statuses/:id/reactions`
708 ### Get an object of emoji to account mappings with accounts that reacted to the post
709 * Method: `GET`
710 * Authentication: optional
711 * Params: None
712 * 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.
713 * Example Response:
714 ```json
715 [
716   {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
717   {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
718 ]
719 ```
720
721 ## `GET /api/v1/pleroma/statuses/:id/reactions/:emoji`
722 ### Get an object of emoji to account mappings with accounts that reacted to the post for a specific emoji
723 * Method: `GET`
724 * Authentication: optional
725 * Params: None
726 * Response: JSON, a list of emoji/account list tuples
727 * Example Response:
728 ```json
729 [
730   {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}
731 ]
732 ```
733
734 ## `POST /api/v1/pleroma/backups`
735 ### Create a user backup archive
736
737 * Method: `POST`
738 * Authentication: required
739 * Params: none
740 * Response: JSON
741 * Example response:
742
743 ```json
744 [{
745     "content_type": "application/zip",
746     "file_size": 0,
747     "inserted_at": "2020-09-10T16:18:03.000Z",
748     "processed": false,
749     "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
750 }]
751 ```
752
753 ## `GET /api/v1/pleroma/backups`
754 ### Lists user backups
755
756 * Method: `GET`
757 * Authentication: not required
758 * Params: none
759 * Response: JSON
760 * Example response:
761
762 ```json
763 [{
764     "content_type": "application/zip",
765     "file_size": 55457,
766     "inserted_at": "2020-09-10T16:18:03.000Z",
767     "processed": true,
768     "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
769 }]
770 ```
771
772 ## `GET /api/oauth_tokens`
773 ### Retrieve a list of active sessions for the user
774 * Method: `GET`
775 * Authentication: required
776 * Params: none
777 * Response: JSON
778 * Example response:
779
780 ```json
781 [
782   {
783     "app_name": "Pleroma FE",
784     "id": 9275,
785     "valid_until": "2121-11-24T15:51:08.234234"
786   },
787   {
788     "app_name": "Patron",
789     "id": 8805,
790     "valid_until": "2121-10-26T18:09:59.857150"
791   },
792   {
793     "app_name": "Soapbox FE",
794     "id": 9727,
795     "valid_until": "2121-12-25T16:52:39.692877"
796   }
797 ]
798 ```
799
800 ## `DELETE /api/oauth_tokens/:id`
801 ### Revoke a user session by its ID
802 * Method: `DELETE`
803 * Authentication: required
804 * Params: none
805 * Response: HTTP 200 on success, 500 on error
806
807 ## `/api/v1/pleroma/settings/:app`
808 ### Gets settings for some application
809 * Method `GET`
810 * Authentication: `read:accounts`
811
812 * Response: JSON. The settings for that application, or empty object if there is none.
813 * Example response:
814 ```json
815 {
816   "some key": "some value"
817 }
818 ```
819
820 ### Updates settings for some application
821 * Method `PATCH`
822 * Authentication: `write:accounts`
823 * Request body: JSON object. The object will be merged recursively with old settings. If some field is set to null, it is removed.
824 * Example request:
825 ```json
826 {
827   "some key": "some value",
828   "key to remove": null,
829   "nested field": {
830     "some key": "some value",
831     "key to remove": null
832   }
833 }
834 ```
835 * Response: JSON. Updated (merged) settings for that application.
836 * Example response:
837 ```json
838 {
839   "some key": "some value",
840   "nested field": {
841     "some key": "some value",
842   }
843 }
844 ```