git.squeep.com Git - akkoma/blob - docs/API/pleroma_api.md

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