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/account/register`
  74 ### Register a new user
  75 * Method `POST`
  76 * Authentication: not required
  77 * Params:
  78     * `nickname`
  79     * `fullname`
  80     * `bio`
  81     * `email`
  82     * `password`
  83     * `confirm`
  84     * `captcha_solution`: optional, contains provider-specific captcha solution,
  85     * `captcha_token`: optional, contains provider-specific captcha token
  86     * `token`: invite token required when the registrations aren't public.
  87 * Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}`
  88 * Example response:
  89 ```json
  90 {
  91         "background_image": null,
  92         "cover_photo": "https://pleroma.soykaf.com/images/banner.png",
  93         "created_at": "Tue Dec 18 16:55:56 +0000 2018",
  94         "default_scope": "public",
  95         "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.",
  96         "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.",
  97         "favourites_count": 0,
  98         "fields": [],
  99         "followers_count": 0,
 100         "following": false,
 101         "follows_you": false,
 102         "friends_count": 0,
 103         "id": 6,
 104         "is_local": true,
 105         "locked": false,
 106         "name": "lain",
 107         "name_html": "lain",
 108         "no_rich_text": false,
 109         "pleroma": {
 110                 "tags": []
 111         },
 112         "profile_image_url": "https://pleroma.soykaf.com/images/avi.png",
 113         "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png",
 114         "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png",
 115         "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png",
 116         "rights": {
 117                 "delete_others_notice": false
 118         },
 119         "screen_name": "lain",
 120         "statuses_count": 0,
 121         "statusnet_blocking": false,
 122         "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain"
 123 }
 124 ```
 125
 126 ## `/api/pleroma/admin/`…
 127 See [Admin-API](admin_api.md)
 128
 129 ## `/api/v1/pleroma/notifications/read`
 130 ### Mark notifications as read
 131 * Method `POST`
 132 * Authentication: required
 133 * Params (mutually exclusive):
 134     * `id`: a single notification id to read
 135     * `max_id`: read all notifications up to this id
 136 * Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
 137
 138 ## `/api/v1/pleroma/accounts/:id/subscribe`
 139 ### Subscribe to receive notifications for all statuses posted by a user
 140 * Method `POST`
 141 * Authentication: required
 142 * Params:
 143     * `id`: account id to subscribe to
 144 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 145 * Example response:
 146 ```json
 147 {
 148   "id": "abcdefg",
 149   "following": true,
 150   "followed_by": false,
 151   "blocking": false,
 152   "muting": false,
 153   "muting_notifications": false,
 154   "subscribing": true,
 155   "requested": false,
 156   "domain_blocking": false,
 157   "showing_reblogs": true,
 158   "endorsed": false
 159 }
 160 ```
 161
 162 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
 163 ### Unsubscribe to stop receiving notifications from user statuses
 164 * Method `POST`
 165 * Authentication: required
 166 * Params:
 167     * `id`: account id to unsubscribe from
 168 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
 169 * Example response:
 170 ```json
 171 {
 172   "id": "abcdefg",
 173   "following": true,
 174   "followed_by": false,
 175   "blocking": false,
 176   "muting": false,
 177   "muting_notifications": false,
 178   "subscribing": false,
 179   "requested": false,
 180   "domain_blocking": false,
 181   "showing_reblogs": true,
 182   "endorsed": false
 183 }
 184 ```
 185
 186 ## `/api/v1/pleroma/accounts/:id/favourites`
 187 ### Returns favorites timeline of any user
 188 * Method `GET`
 189 * Authentication: not required
 190 * Params:
 191     * `id`: the id of the account for whom to return results
 192     * `limit`: optional, the number of records to retrieve
 193     * `since_id`: optional, returns results that are more recent than the specified id
 194     * `max_id`: optional, returns results that are older than the specified id
 195 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
 196 * Example response:
 197 ```json
 198 [
 199   {
 200     "account": {
 201       "id": "9hptFmUF3ztxYh3Svg",
 202       "url": "https://pleroma.example.org/users/nick2",
 203       "username": "nick2",
 204       ...
 205     },
 206     "application": {"name": "Web", "website": null},
 207     "bookmarked": false,
 208     "card": null,
 209     "content": "This is :moominmamma: note 0",
 210     "created_at": "2019-04-15T15:42:15.000Z",
 211     "emojis": [],
 212     "favourited": false,
 213     "favourites_count": 1,
 214     "id": "9hptFmVJ02khbzYJaS",
 215     "in_reply_to_account_id": null,
 216     "in_reply_to_id": null,
 217     "language": null,
 218     "media_attachments": [],
 219     "mentions": [],
 220     "muted": false,
 221     "pinned": false,
 222     "pleroma": {
 223       "content": {"text/plain": "This is :moominmamma: note 0"},
 224       "conversation_id": 13679,
 225       "local": true,
 226       "spoiler_text": {"text/plain": "2hu"}
 227     },
 228     "reblog": null,
 229     "reblogged": false,
 230     "reblogs_count": 0,
 231     "replies_count": 0,
 232     "sensitive": false,
 233     "spoiler_text": "2hu",
 234     "tags": [{"name": "2hu", "url": "/tag/2hu"}],
 235     "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
 236     "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
 237     "visibility": "public"
 238   }
 239 ]
 240 ```
 241
 242 ## `/api/v1/pleroma/accounts/update_*`
 243 ### Set and clear account avatar, banner, and background
 244
 245 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
 246 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
 247 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
 248
 249 ## `/api/v1/pleroma/accounts/confirmation_resend`
 250 ### Resend confirmation email
 251 * Method `POST`
 252 * Params:
 253     * `email`: email of that needs to be verified
 254 * Authentication: not required
 255 * Response: 204 No Content
 256
 257 ## `/api/v1/pleroma/mascot`
 258 ### Gets user mascot image
 259 * Method `GET`
 260 * Authentication: required
 261
 262 * Response: JSON. Returns a mastodon media attachment entity.
 263 * Example response:
 264 ```json
 265 {
 266     "id": "abcdefg",
 267     "url": "https://pleroma.example.org/media/abcdefg.png",
 268     "type": "image",
 269     "pleroma": {
 270         "mime_type": "image/png"
 271     }
 272 }
 273 ```
 274
 275 ### Updates user mascot image
 276 * Method `PUT`
 277 * Authentication: required
 278 * Params:
 279     * `image`: Multipart image
 280 * Response: JSON. Returns a mastodon media attachment entity
 281   when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
 282 * Example response:
 283 ```json
 284 {
 285     "id": "abcdefg",
 286     "url": "https://pleroma.example.org/media/abcdefg.png",
 287     "type": "image",
 288     "pleroma": {
 289         "mime_type": "image/png"
 290     }
 291 }
 292 ```
 293 * Note: Behaves exactly the same as `POST /api/v1/upload`.
 294   Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
 295
 296 ## `/api/pleroma/notification_settings`
 297 ### Updates user notification settings
 298 * Method `PUT`
 299 * Authentication: required
 300 * Params:
 301     * `followers`: BOOLEAN field, receives notifications from followers
 302     * `follows`: BOOLEAN field, receives notifications from people the user follows
 303     * `remote`: BOOLEAN field, receives notifications from people on remote instances
 304     * `local`: BOOLEAN field, receives notifications from people on the local instance
 305     * `privacy_option`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
 306 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
 307
 308 ## `/api/pleroma/healthcheck`
 309 ### Healthcheck endpoint with additional system data.
 310 * Method `GET`
 311 * Authentication: not required
 312 * Params: none
 313 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 314 * Example response:
 315 ```json
 316 {
 317   "pool_size": 0, # database connection pool
 318   "active": 0, # active processes
 319   "idle": 0, # idle processes
 320   "memory_used": 0.00, # Memory used
 321   "healthy": true, # Instance state
 322   "job_queue_stats": {} # Job queue stats
 323 }
 324 ```
 325
 326 ## `/api/pleroma/change_email`
 327 ### Change account email
 328 * Method `POST`
 329 * Authentication: required
 330 * Params:
 331     * `password`: user's password
 332     * `email`: new email
 333 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
 334 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
 335
 336 # Pleroma Conversations
 337
 338 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
 339
 340 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
 341 2. Pleroma Conversations statuses can be requested by Conversation id.
 342 3. Pleroma Conversations can be replied to.
 343
 344 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.
 345
 346 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.
 347
 348
 349 ## `GET /api/v1/pleroma/conversations/:id/statuses`
 350 ### Timeline for a given conversation
 351 * Method `GET`
 352 * Authentication: required
 353 * Params: Like other timelines
 354 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 355
 356 ## `GET /api/v1/pleroma/conversations/:id`
 357 ### The conversation with the given ID.
 358 * Method `GET`
 359 * Authentication: required
 360 * Params: None
 361 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
 362
 363 ## `PATCH /api/v1/pleroma/conversations/:id`
 364 ### Update a conversation. Used to change the set of recipients.
 365 * Method `PATCH`
 366 * Authentication: required
 367 * Params:
 368     * `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.
 369 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
 370
 371 ## `GET /api/v1/pleroma/conversations/read`
 372 ### Marks all user's conversations as read.
 373 * Method `POST`
 374 * Authentication: required
 375 * Params: None
 376 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
 377
 378 ## `GET /api/pleroma/emoji/packs`
 379 ### Lists the custom emoji packs on the server
 380 * Method `GET`
 381 * Authentication: not required
 382 * Params: None
 383 * Response: JSON, "ok" and 200 status and the JSON hashmap of "pack name" to "pack contents"
 384
 385 ## `PUT /api/pleroma/emoji/packs/:name`
 386 ### Creates an empty custom emoji pack
 387 * Method `PUT`
 388 * Authentication: required
 389 * Params: None
 390 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
 391
 392 ## `DELETE /api/pleroma/emoji/packs/:name`
 393 ### Delete a custom emoji pack
 394 * Method `DELETE`
 395 * Authentication: required
 396 * Params: None
 397 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
 398
 399 ## `POST /api/pleroma/emoji/packs/:name/update_file`
 400 ### Update a file in a custom emoji pack
 401 * Method `POST`
 402 * Authentication: required
 403 * Params:
 404     * if the `action` is `add`, adds an emoji named `shortcode` to the pack `pack_name`,
 405       that means that the emoji file needs to be uploaded with the request
 406       (thus requiring it to be a multipart request) and be named `file`.
 407       There can also be an optional `filename` that will be the new emoji file name
 408       (if it's not there, the name will be taken from the uploaded file).
 409     * if the `action` is `update`, changes emoji shortcode
 410       (from `shortcode` to `new_shortcode` or moves the file (from the current filename to `new_filename`)
 411     * if the `action` is `remove`, removes the emoji named `shortcode` and it's associated file
 412 * Response: JSON, updated "files" section of the pack and 200 status, 409 if the trying to use a shortcode
 413   that is already taken, 400 if there was an error with the shortcode, filename or file (additional info
 414   in the "error" part of the response JSON)
 415
 416 ## `POST /api/pleroma/emoji/packs/:name/update_metadata`
 417 ### Updates (replaces) pack metadata
 418 * Method `POST`
 419 * Authentication: required
 420 * Params:
 421   * `new_data`: new metadata to replace the old one
 422 * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
 423   problem with the new metadata (the error is specified in the "error" part of the response JSON)
 424
 425 ## `POST /api/pleroma/emoji/packs/download_from`
 426 ### Requests the instance to download the pack from another instance
 427 * Method `POST`
 428 * Authentication: required
 429 * Params:
 430   * `instance_address`: the address of the instance to download from
 431   * `pack_name`: the pack to download from that instance
 432 * Response: JSON, "ok" and 200 status if the pack was downloaded, or 500 if there were
 433   errors downloading the pack
 434
 435 ## `POST /api/pleroma/emoji/packs/list_from`
 436 ### Requests the instance to list the packs from another instance
 437 * Method `POST`
 438 * Authentication: required
 439 * Params:
 440   * `instance_address`: the address of the instance to download from
 441 * Response: JSON with the pack list, same as if the request was made to that instance's
 442   list endpoint directly + 200 status
 443
 444 ## `GET /api/pleroma/emoji/packs/:name/download_shared`
 445 ### Requests a local pack from the instance
 446 * Method `GET`
 447 * Authentication: not required
 448 * Params: None
 449 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
 450   404 if the pack does not exist
 451
 452 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
 453 ### Requests a list of current and recent Listen activities for an account
 454 * Method `GET`
 455 * Authentication: not required
 456 * Params: None
 457 * Response: An array of media metadata entities.
 458 * Example response:
 459 ```json
 460 [
 461    {
 462        "account": {...},
 463        "id": "1234",
 464        "title": "Some Title",
 465        "artist": "Some Artist",
 466        "album": "Some Album",
 467        "length": 180000,
 468        "created_at": "2019-09-28T12:40:45.000Z"
 469    }
 470 ]
 471 ```
 472
 473 ## `POST /api/v1/pleroma/scrobble`
 474 ### Creates a new Listen activity for an account
 475 * Method `POST`
 476 * Authentication: required
 477 * Params:
 478   * `title`: the title of the media playing
 479   * `album`: the album of the media playing [optional]
 480   * `artist`: the artist of the media playing [optional]
 481   * `length`: the length of the media playing [optional]
 482 * Response: the newly created media metadata entity representing the Listen activity
 483
 484 # Emoji Reactions
 485
 486 Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character.
 487
 488 ## `POST /api/v1/pleroma/statuses/:id/react_with_emoji`
 489 ### React to a post with a unicode emoji
 490 * Method: `POST`
 491 * Authentication: required
 492 * Params: `emoji`: A single character unicode emoji
 493 * Response: JSON, the status.
 494
 495 ## `POST /api/v1/pleroma/statuses/:id/unreact_with_emoji`
 496 ### Remove a reaction to a post with a unicode emoji
 497 * Method: `POST`
 498 * Authentication: required
 499 * Params: `emoji`: A single character unicode emoji
 500 * Response: JSON, the status.
 501
 502 ## `GET /api/v1/pleroma/statuses/:id/emoji_reactions_by`
 503 ### Get an object of emoji to account mappings with accounts that reacted to the post
 504 * Method: `GET`
 505 * Authentication: optional
 506 * Params: None
 507 * Response: JSON, a map of emoji to account list mappings.
 508 * Example Response:
 509 ```json
 510 {
 511   "😀" => [{"id" => "xyz.."...}, {"id" => "zyx..."}],
 512   "🗡" => [{"id" => "abc..."}]
 513 }
 514 ```