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