First
[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 ## `/api/v1/pleroma/accounts/update_*`
255 ### Set and clear account avatar, banner, and background
256
257 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
258 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
259 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
260
261 ## `/api/v1/pleroma/accounts/confirmation_resend`
262 ### Resend confirmation email
263 * Method `POST`
264 * Params:
265     * `email`: email of that needs to be verified
266 * Authentication: not required
267 * Response: 204 No Content
268
269 ## `/api/v1/pleroma/mascot`
270 ### Gets user mascot image
271 * Method `GET`
272 * Authentication: required
273
274 * Response: JSON. Returns a mastodon media attachment entity.
275 * Example response:
276 ```json
277 {
278     "id": "abcdefg",
279     "url": "https://pleroma.example.org/media/abcdefg.png",
280     "type": "image",
281     "pleroma": {
282         "mime_type": "image/png"
283     }
284 }
285 ```
286
287 ### Updates user mascot image
288 * Method `PUT`
289 * Authentication: required
290 * Params:
291     * `file`: Multipart image
292 * Response: JSON. Returns a mastodon media attachment entity
293   when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
294 * Example response:
295 ```json
296 {
297     "id": "abcdefg",
298     "url": "https://pleroma.example.org/media/abcdefg.png",
299     "type": "image",
300     "pleroma": {
301         "mime_type": "image/png"
302     }
303 }
304 ```
305 * Note: Behaves exactly the same as `POST /api/v1/upload`.
306   Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
307
308 ## `/api/pleroma/notification_settings`
309 ### Updates user notification settings
310 * Method `PUT`
311 * Authentication: required
312 * Params:
313     * `block_from_strangers`: BOOLEAN field, blocks notifications from accounts you do not follow
314     * `hide_notification_contents`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
315 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
316
317 ## `/api/v1/pleroma/healthcheck`
318 ### Healthcheck endpoint with additional system data.
319 * Method `GET`
320 * Authentication: not required
321 * Params: none
322 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
323 * Example response:
324 ```json
325 {
326   "pool_size": 0, # database connection pool
327   "active": 0, # active processes
328   "idle": 0, # idle processes
329   "memory_used": 0.00, # Memory used
330   "healthy": true, # Instance state
331   "job_queue_stats": {} # Job queue stats
332 }
333 ```
334
335 ## `/api/pleroma/change_email`
336 ### Change account email
337 * Method `POST`
338 * Authentication: required
339 * Params:
340     * `password`: user's password
341     * `email`: new email
342 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
343 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
344
345 ## `/api/pleroma/move_account`
346 ### Move account
347 * Method `POST`
348 * Authentication: required
349 * Params:
350     * `password`: user's password
351     * `target_account`: the nickname of the target account (e.g. `foo@example.org`)
352 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
353 * 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").
354
355 ## `/api/pleroma/aliases`
356 ### Get aliases of the current account
357 * Method `GET`
358 * Authentication: required
359 * Response: JSON. Returns `{"aliases": [alias, ...]}`, where `alias` is the nickname of an alias, e.g. `foo@example.org`.
360
361 ### Add alias to the current account
362 * Method `PUT`
363 * Authentication: required
364 * Params:
365     * `alias`: the nickname of the alias to add, e.g. `foo@example.org`.
366 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
367
368 ### Delete alias from the current account
369 * Method `DELETE`
370 * Authentication: required
371 * Params:
372     * `alias`: the nickname of the alias to delete, e.g. `foo@example.org`.
373 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
374
375 # Pleroma Conversations
376
377 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
378
379 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
380 2. Pleroma Conversations statuses can be requested by Conversation id.
381 3. Pleroma Conversations can be replied to.
382
383 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.
384
385 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.
386
387 âš  Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`.
388
389 ## `GET /api/v1/pleroma/conversations/:id/statuses`
390 ### Timeline for a given conversation
391 * Method `GET`
392 * Authentication: required
393 * Params: Like other timelines
394 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
395
396 ## `GET /api/v1/pleroma/conversations/:id`
397 ### The conversation with the given ID.
398 * Method `GET`
399 * Authentication: required
400 * Params: None
401 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
402
403 ## `PATCH /api/v1/pleroma/conversations/:id`
404 ### Update a conversation. Used to change the set of recipients.
405 * Method `PATCH`
406 * Authentication: required
407 * Params:
408     * `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.
409 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
410
411 ## `POST /api/v1/pleroma/conversations/read`
412 ### Marks all user's conversations as read.
413 * Method `POST`
414 * Authentication: required
415 * Params: None
416 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
417
418 ## `GET /api/v1/pleroma/emoji/pack?name=:name`
419
420 ### Get pack.json for the pack
421
422 * Method `GET`
423 * Authentication: not required
424 * Params:
425   * `page`: page number for files (default 1)
426   * `page_size`: page size for files (default 30)
427 * Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
428
429 ```json
430 {
431   "files": {...},
432   "files_count": 0, // emoji count in pack
433   "pack": {...}
434 }
435 ```
436
437 ## `POST /api/v1/pleroma/emoji/pack?name=:name`
438
439 ### Creates an empty pack
440
441 * Method `POST`
442 * Authentication: required (admin)
443 * Params:
444   * `name`: pack name
445 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
446
447 ## `PATCH /api/v1/pleroma/emoji/pack?name=:name`
448
449 ### Updates (replaces) pack metadata
450
451 * Method `PATCH`
452 * Authentication: required (admin)
453 * Params:
454   * `name`: pack name
455   * `metadata`: metadata to replace the old one
456     * `license`: Pack license
457     * `homepage`: Pack home page url
458     * `description`: Pack description
459     * `fallback-src`: Fallback url to download pack from
460     * `fallback-src-sha256`: SHA256 encoded for fallback pack archive
461     * `share-files`: is pack allowed for sharing (boolean)
462 * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
463   problem with the new metadata (the error is specified in the "error" part of the response JSON)
464
465 ## `DELETE /api/v1/pleroma/emoji/pack?name=:name`
466
467 ### Delete a custom emoji pack
468
469 * Method `DELETE`
470 * Authentication: required (admin)
471 * Params:
472   * `name`: pack name
473 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
474
475 ## `GET /api/v1/pleroma/emoji/packs/import`
476
477 ### Imports packs from filesystem
478
479 * Method `GET`
480 * Authentication: required (admin)
481 * Params: None
482 * Response: JSON, returns a list of imported packs.
483
484 ## `GET /api/v1/pleroma/emoji/packs/remote`
485
486 ### Make request to another instance for packs list
487
488 * Method `GET`
489 * Authentication: required (admin)
490 * Params:
491   * `url`: url of the instance to get packs from
492   * `page`: page number for packs (default 1)
493   * `page_size`: page size for packs (default 50)
494 * Response: JSON with the pack list, hashmap with pack name and pack contents
495
496 ## `POST /api/v1/pleroma/emoji/packs/download`
497
498 ### Download pack from another instance
499
500 * Method `POST`
501 * Authentication: required (admin)
502 * Params:
503   * `url`: url of the instance to download from
504   * `name`: pack to download from that instance
505   * `as`: (*optional*) name how to save pack
506 * Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
507   errors downloading the pack
508
509 ## `POST /api/v1/pleroma/emoji/packs/files?name=:name`
510
511 ### Add new file to the pack
512
513 * Method `POST`
514 * Authentication: required (admin)
515 * Params:
516   * `name`: pack name
517   * `file`: file needs to be uploaded with the multipart request or link to remote file.
518   * `shortcode`: (*optional*) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.
519   * `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename.
520 * Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
521
522 ## `PATCH /api/v1/pleroma/emoji/packs/files?name=:name`
523
524 ### Update emoji file from pack
525
526 * Method `PATCH`
527 * Authentication: required (admin)
528 * Params:
529   * `name`: pack name
530   * `shortcode`: emoji file shortcode
531   * `new_shortcode`: new emoji file shortcode
532   * `new_filename`: new filename for emoji file
533   * `force`: (*optional*) with true value to overwrite existing emoji with new shortcode
534 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
535
536 ## `DELETE /api/v1/pleroma/emoji/packs/files?name=:name`
537
538 ### Delete emoji file from pack
539
540 * Method `DELETE`
541 * Authentication: required (admin)
542 * Params:
543   * `name`: pack name
544   * `shortcode`: emoji file shortcode
545 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
546
547 ## `GET /api/v1/pleroma/emoji/packs`
548
549 ### Lists local custom emoji packs
550
551 * Method `GET`
552 * Authentication: not required
553 * Params:
554   * `page`: page number for packs (default 1)
555   * `page_size`: page size for packs (default 50)
556 * Response: `packs` key with JSON hashmap of pack name to pack contents and `count` key for count of packs.
557
558 ```json
559 {
560   "packs": {
561     "pack_name": {...}, // pack contents
562     ...
563   },
564   "count": 0 // packs count
565 }
566 ```
567
568 ## `GET /api/v1/pleroma/emoji/packs/archive?name=:name`
569
570 ### Requests a local pack archive from the instance
571
572 * Method `GET`
573 * Authentication: not required
574 * Params:
575   * `name`: pack name
576 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
577   404 if the pack does not exist
578
579 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
580 ### Requests a list of current and recent Listen activities for an account
581 * Method `GET`
582 * Authentication: not required
583 * Params: None
584 * Response: An array of media metadata entities.
585 * Example response:
586 ```json
587 [
588    {
589        "account": {...},
590        "id": "1234",
591        "title": "Some Title",
592        "artist": "Some Artist",
593        "album": "Some Album",
594        "length": 180000,
595        "created_at": "2019-09-28T12:40:45.000Z"
596    }
597 ]
598 ```
599
600 ## `POST /api/v1/pleroma/scrobble`
601 ### Creates a new Listen activity for an account
602 * Method `POST`
603 * Authentication: required
604 * Params:
605   * `title`: the title of the media playing
606   * `album`: the album of the media playing [optional]
607   * `artist`: the artist of the media playing [optional]
608   * `length`: the length of the media playing [optional]
609 * Response: the newly created media metadata entity representing the Listen activity
610
611 # Emoji Reactions
612
613 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.
614
615 ## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji`
616 ### React to a post with a unicode emoji
617 * Method: `PUT`
618 * Authentication: required
619 * Params: `emoji`: A unicode RGI emoji or a regional indicator
620 * Response: JSON, the status.
621
622 ## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji`
623 ### Remove a reaction to a post with a unicode emoji
624 * Method: `DELETE`
625 * Authentication: required
626 * Params: `emoji`: A unicode RGI emoji or a regional indicator
627 * Response: JSON, the status.
628
629 ## `GET /api/v1/pleroma/statuses/:id/reactions`
630 ### Get an object of emoji to account mappings with accounts that reacted to the post
631 * Method: `GET`
632 * Authentication: optional
633 * Params: None
634 * 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.
635 * Example Response:
636 ```json
637 [
638   {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
639   {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
640 ]
641 ```
642
643 ## `GET /api/v1/pleroma/statuses/:id/reactions/:emoji`
644 ### Get an object of emoji to account mappings with accounts that reacted to the post for a specific emoji
645 * Method: `GET`
646 * Authentication: optional
647 * Params: None
648 * Response: JSON, a list of emoji/account list tuples
649 * Example Response:
650 ```json
651 [
652   {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}
653 ]
654 ```
655
656 ## `POST /api/v1/pleroma/backups`
657 ### Create a user backup archive
658
659 * Method: `POST`
660 * Authentication: required
661 * Params: none
662 * Response: JSON
663 * Example response:
664
665 ```json
666 [{
667     "content_type": "application/zip",
668     "file_size": 0,
669     "inserted_at": "2020-09-10T16:18:03.000Z",
670     "processed": false,
671     "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
672 }]
673 ```
674
675 ## `GET /api/v1/pleroma/backups`
676 ### Lists user backups
677
678 * Method: `GET`
679 * Authentication: not required
680 * Params: none
681 * Response: JSON
682 * Example response:
683
684 ```json
685 [{
686     "content_type": "application/zip",
687     "file_size": 55457,
688     "inserted_at": "2020-09-10T16:18:03.000Z",
689     "processed": true,
690     "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
691 }]
692 ```
693
694 ## `GET /api/oauth_tokens`
695 ### Retrieve a list of active sessions for the user
696 * Method: `GET`
697 * Authentication: required
698 * Params: none
699 * Response: JSON
700 * Example response:
701
702 ```json
703 [
704   {
705     "app_name": "Pleroma FE",
706     "id": 9275,
707     "valid_until": "2121-11-24T15:51:08.234234"
708   },
709   {
710     "app_name": "Patron",
711     "id": 8805,
712     "valid_until": "2121-10-26T18:09:59.857150"
713   },
714   {
715     "app_name": "Soapbox FE",
716     "id": 9727,
717     "valid_until": "2121-12-25T16:52:39.692877"
718   }
719 ]
720 ```
721
722 ## `DELETE /api/oauth_tokens/:id`
723 ### Revoke a user session by its ID
724 * Method: `DELETE`
725 * Authentication: required
726 * Params: none
727 * Response: HTTP 200 on success, 500 on error
728
729 ## `/api/v1/pleroma/settings/:app`
730 ### Gets settings for some application
731 * Method `GET`
732 * Authentication: `read:accounts`
733
734 * Response: JSON. The settings for that application, or empty object if there is none.
735 * Example response:
736 ```json
737 {
738   "some key": "some value"
739 }
740 ```
741
742 ### Updates settings for some application
743 * Method `PATCH`
744 * Authentication: `write:accounts`
745 * Request body: JSON object. The object will be merged recursively with old settings. If some field is set to null, it is removed.
746 * Example request:
747 ```json
748 {
749   "some key": "some value",
750   "key to remove": null,
751   "nested field": {
752     "some key": "some value",
753     "key to remove": null
754   }
755 }
756 ```
757 * Response: JSON. Updated (merged) settings for that application.
758 * Example response:
759 ```json
760 {
761   "some key": "some value",
762   "nested field": {
763     "some key": "some value",
764   }
765 }
766 ```