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