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