Git of dcc - anni/blob - 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 ```