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).
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`.
7 The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/api/pleroma/*` will be deprecated in the future).
9 ## `/api/v1/pleroma/emoji`
10 ### Lists the custom emoji on that server.
12 * Authentication: not required
22 "image_url": "/finmoji/128px/girlpower-128.png"
28 "image_url": "/finmoji/128px/education-128.png"
34 "image_url": "/finmoji/128px/finnishlove-128.png"
38 * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
40 ## `/api/pleroma/follow_import`
41 ### Imports your follows, for example from a Mastodon CSV file.
43 * Authentication: required
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.
49 ## `/api/pleroma/blocks_import`
50 ### Imports your blocks.
52 * Authentication: required
54 * `list`: STRING or FILE containing a whitespace-separated list of accounts to block
55 * Response: HTTP 200 on success, 500 on error
57 ## `/api/pleroma/mutes_import`
58 ### Imports your mutes.
60 * Authentication: required
62 * `list`: STRING or FILE containing a whitespace-separated list of accounts to mute
63 * Response: HTTP 200 on success, 500 on error
65 ## `/api/v1/pleroma/captcha`
68 * Authentication: not required
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}`
73 ## `/api/pleroma/delete_account`
76 * Authentication: required
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."}`
82 ## `/api/pleroma/disable_account`
83 ### Disable an account
85 * Authentication: required
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."}`
91 ## `/api/pleroma/accounts/mfa`
92 #### Gets current MFA settings
94 * Authentication: required
95 * OAuth scope: `read:security`
96 * Response: JSON. Returns `{"settings": {"enabled": "false", "totp": false }}`
97 * Note: `enabled` is whether multi-factor auth is enabled for the user in general, while `totp` is one type of MFA.
99 ## `/api/pleroma/accounts/mfa/setup/totp`
100 #### Pre-setup the MFA/TOTP method
102 * Authentication: required
103 * OAuth scope: `write:security`
104 * Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]" }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}`
106 ## `/api/pleroma/accounts/mfa/confirm/totp`
107 #### Confirms & enables MFA/TOTP support for user account.
109 * Authentication: required
110 * OAuth scope: `write:security`
112 * `password`: user's password
113 * `code`: token from TOTP App
114 * Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
117 ## `/api/pleroma/accounts/mfa/totp`
118 #### Disables MFA/TOTP method for user account.
120 * Authentication: required
121 * OAuth scope: `write:security`
123 * `password`: user's password
124 * Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
125 * Example response: `{"error": "Invalid password."}`
127 ## `/api/pleroma/accounts/mfa/backup_codes`
128 #### Generstes backup codes MFA for user account.
130 * Authentication: required
131 * OAuth scope: `write:security`
132 * Response: JSON. Returns `{"codes": codes}` when successful, otherwise HTTP 422 `{"error": "[error message]"}`
134 ## `/api/v1/pleroma/admin/`
135 See [Admin-API](admin_api.md)
137 ## `/api/v1/pleroma/notifications/read`
138 ### Mark notifications as read
140 * Authentication: required
141 * Params (mutually exclusive):
142 * `id`: a single notification id to read
143 * `max_id`: read all notifications up to this id
144 * Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
146 ## `/api/v1/pleroma/accounts/:id/subscribe`
147 ### Subscribe to receive notifications for all statuses posted by a user
149 * Authentication: required
151 * `id`: account id to subscribe to
152 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
158 "followed_by": false,
161 "muting_notifications": false,
165 "domain_blocking": false,
166 "showing_reblogs": true,
172 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
173 ### Unsubscribe to stop receiving notifications from user statuses
175 * Authentication: required
177 * `id`: account id to unsubscribe from
178 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
184 "followed_by": false,
187 "muting_notifications": false,
188 "subscribing": false,
191 "domain_blocking": false,
192 "showing_reblogs": true,
198 ## `/api/v1/pleroma/accounts/:id/favourites`
199 ### Returns favorites timeline of any user
201 * Authentication: not required
203 * `id`: the id of the account for whom to return results
204 * `limit`: optional, the number of records to retrieve
205 * `since_id`: optional, returns results that are more recent than the specified id
206 * `max_id`: optional, returns results that are older than the specified id
207 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
213 "id": "9hptFmUF3ztxYh3Svg",
214 "url": "https://pleroma.example.org/users/nick2",
218 "application": {"name": "Web", "website": null},
221 "content": "This is :moominmamma: note 0",
222 "created_at": "2019-04-15T15:42:15.000Z",
225 "favourites_count": 1,
226 "id": "9hptFmVJ02khbzYJaS",
227 "in_reply_to_account_id": null,
228 "in_reply_to_id": null,
230 "media_attachments": [],
235 "content": {"text/plain": "This is :moominmamma: note 0"},
236 "conversation_id": 13679,
238 "spoiler_text": {"text/plain": "2hu"}
245 "spoiler_text": "2hu",
246 "tags": [{"name": "2hu", "url": "/tag/2hu"}],
247 "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
248 "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
249 "visibility": "public"
255 ## `/api/v1/pleroma/accounts/:id/endorsements`
256 ### Returns users endorsed by a user
258 * Authentication: not required
260 * `id`: the id of the account for whom to return results
261 * Response: JSON, returns a list of Mastodon Account entities
263 ## `/api/v1/pleroma/accounts/update_*`
264 ### Set and clear account avatar, banner, and background
266 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
267 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
268 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
270 ## `/api/v1/pleroma/accounts/confirmation_resend`
271 ### Resend confirmation email
274 * `email`: email of that needs to be verified
275 * Authentication: not required
276 * Response: 204 No Content
278 ## `/api/v1/pleroma/statuses/:id/quotes`
279 ### Gets quotes for a given status
281 * Authentication: not required
283 * `id`: the id of the status
284 * Response: JSON, returns a list of Mastodon Status entities
286 ## `GET /api/v1/pleroma/bookmark_folders`
287 ### Gets user bookmark folders
288 * Authentication: required
290 * Response: JSON. Returns a list of bookmark folders.
295 "id": "9umDrYheeY451cQnEe",
296 "name": "Read later",
305 ## `POST /api/v1/pleroma/bookmark_folders`
306 ### Creates a bookmark folder
307 * Authentication: required
310 * `name`: folder name
311 * `emoji`: folder emoji (optional)
312 * Response: JSON. Returns a single bookmark folder.
314 ## `PATCH /api/v1/pleroma/bookmark_folders/:id`
315 ### Updates a bookmark folder
316 * Authentication: required
320 * `name`: folder name (optional)
321 * `emoji`: folder emoji (optional)
322 * Response: JSON. Returns a single bookmark folder.
324 ## `DELETE /api/v1/pleroma/bookmark_folders/:id`
325 ### Deletes a bookmark folder
326 * Authentication: required
330 * Response: JSON. Returns a single bookmark folder.
332 ## `/api/v1/pleroma/mascot`
333 ### Gets user mascot image
335 * Authentication: required
337 * Response: JSON. Returns a mastodon media attachment entity.
342 "url": "https://pleroma.example.org/media/abcdefg.png",
345 "mime_type": "image/png"
350 ### Updates user mascot image
352 * Authentication: required
354 * `file`: Multipart image
355 * Response: JSON. Returns a mastodon media attachment entity
356 when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
361 "url": "https://pleroma.example.org/media/abcdefg.png",
364 "mime_type": "image/png"
368 * Note: Behaves exactly the same as `POST /api/v1/upload`.
369 Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
371 ## `/api/pleroma/notification_settings`
372 ### Updates user notification settings
374 * Authentication: required
376 * `block_from_strangers`: BOOLEAN field, blocks notifications from accounts you do not follow
377 * `hide_notification_contents`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
378 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
380 ## `/api/v1/pleroma/healthcheck`
381 ### Healthcheck endpoint with additional system data.
383 * Authentication: not required
385 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
389 "pool_size": 0, # database connection pool
390 "active": 0, # active processes
391 "idle": 0, # idle processes
392 "memory_used": 0.00, # Memory used
393 "healthy": true, # Instance state
394 "job_queue_stats": {} # Job queue stats
398 ## `/api/pleroma/change_email`
399 ### Change account email
401 * Authentication: required
403 * `password`: user's password
405 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
406 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
408 ## `/api/pleroma/move_account`
411 * Authentication: required
413 * `password`: user's password
414 * `target_account`: the nickname of the target account (e.g. `foo@example.org`)
415 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
416 * Note: This endpoint emits a `Move` activity to all followers of the current account. Some remote servers will automatically unfollow the current account and follow the target account upon seeing this, but this depends on the remote server implementation and cannot be guaranteed. For local followers , they will automatically unfollow and follow if and only if they have set the `allow_following_move` preference ("Allow auto-follow when following account moves").
418 ## `/api/pleroma/aliases`
419 ### Get aliases of the current account
421 * Authentication: required
422 * Response: JSON. Returns `{"aliases": [alias, ...]}`, where `alias` is the nickname of an alias, e.g. `foo@example.org`.
424 ### Add alias to the current account
426 * Authentication: required
428 * `alias`: the nickname of the alias to add, e.g. `foo@example.org`.
429 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
431 ### Delete alias from the current account
433 * Authentication: required
435 * `alias`: the nickname of the alias to delete, e.g. `foo@example.org`.
436 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
438 ## `/api/v1/pleroma/remote_interaction`
439 ## Interact with profile or status from remote account
441 * Authentication: not required
443 * `ap_id`: Profile or status ActivityPub ID
444 * `profile`: Remote profile webfinger
445 * Response: JSON. Returns `{"url": "[redirect url]"}` on success, `{"error": "[error message]"}` otherwise
447 # Pleroma Conversations
449 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
451 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
452 2. Pleroma Conversations statuses can be requested by Conversation id.
453 3. Pleroma Conversations can be replied to.
455 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.
457 The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visibility to direct and address only the people who are the recipients of that Conversation.
459 âš Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`.
461 ## `GET /api/v1/pleroma/conversations/:id/statuses`
462 ### Timeline for a given conversation
464 * Authentication: required
465 * Params: Like other timelines
466 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
468 ## `GET /api/v1/pleroma/conversations/:id`
469 ### The conversation with the given ID.
471 * Authentication: required
473 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
475 ## `PATCH /api/v1/pleroma/conversations/:id`
476 ### Update a conversation. Used to change the set of recipients.
478 * Authentication: required
480 * `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.
481 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
483 ## `POST /api/v1/pleroma/conversations/read`
484 ### Marks all user's conversations as read.
486 * Authentication: required
488 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
490 ## `GET /api/v1/pleroma/emoji/pack?name=:name`
492 ### Get pack.json for the pack
495 * Authentication: not required
497 * `page`: page number for files (default 1)
498 * `page_size`: page size for files (default 30)
499 * Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
504 "files_count": 0, // emoji count in pack
509 ## `POST /api/v1/pleroma/emoji/pack?name=:name`
511 ### Creates an empty pack
514 * Authentication: required (admin)
517 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
519 ## `PATCH /api/v1/pleroma/emoji/pack?name=:name`
521 ### Updates (replaces) pack metadata
524 * Authentication: required (admin)
527 * `metadata`: metadata to replace the old one
528 * `license`: Pack license
529 * `homepage`: Pack home page url
530 * `description`: Pack description
531 * `fallback-src`: Fallback url to download pack from
532 * `fallback-src-sha256`: SHA256 encoded for fallback pack archive
533 * `share-files`: is pack allowed for sharing (boolean)
534 * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
535 problem with the new metadata (the error is specified in the "error" part of the response JSON)
537 ## `DELETE /api/v1/pleroma/emoji/pack?name=:name`
539 ### Delete a custom emoji pack
542 * Authentication: required (admin)
545 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
547 ## `GET /api/v1/pleroma/emoji/packs/import`
549 ### Imports packs from filesystem
552 * Authentication: required (admin)
554 * Response: JSON, returns a list of imported packs.
556 ## `GET /api/v1/pleroma/emoji/packs/remote`
558 ### Make request to another instance for packs list
561 * Authentication: required (admin)
563 * `url`: url of the instance to get packs from
564 * `page`: page number for packs (default 1)
565 * `page_size`: page size for packs (default 50)
566 * Response: JSON with the pack list, hashmap with pack name and pack contents
568 ## `POST /api/v1/pleroma/emoji/packs/download`
570 ### Download pack from another instance
573 * Authentication: required (admin)
575 * `url`: url of the instance to download from
576 * `name`: pack to download from that instance
577 * `as`: (*optional*) name how to save pack
578 * Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
579 errors downloading the pack
581 ## `POST /api/v1/pleroma/emoji/packs/files?name=:name`
583 ### Add new file to the pack
586 * Authentication: required (admin)
589 * `file`: file needs to be uploaded with the multipart request or link to remote file.
590 * `shortcode`: (*optional*) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.
591 * `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename.
592 * Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
594 ## `PATCH /api/v1/pleroma/emoji/packs/files?name=:name`
596 ### Update emoji file from pack
599 * Authentication: required (admin)
602 * `shortcode`: emoji file shortcode
603 * `new_shortcode`: new emoji file shortcode
604 * `new_filename`: new filename for emoji file
605 * `force`: (*optional*) with true value to overwrite existing emoji with new shortcode
606 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
608 ## `DELETE /api/v1/pleroma/emoji/packs/files?name=:name`
610 ### Delete emoji file from pack
613 * Authentication: required (admin)
616 * `shortcode`: emoji file shortcode
617 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
619 ## `GET /api/v1/pleroma/emoji/packs`
621 ### Lists local custom emoji packs
624 * Authentication: not required
626 * `page`: page number for packs (default 1)
627 * `page_size`: page size for packs (default 50)
628 * Response: `packs` key with JSON hashmap of pack name to pack contents and `count` key for count of packs.
633 "pack_name": {...}, // pack contents
636 "count": 0 // packs count
640 ## `GET /api/v1/pleroma/emoji/packs/archive?name=:name`
642 ### Requests a local pack archive from the instance
645 * Authentication: not required
648 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
649 404 if the pack does not exist
651 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
653 Audio scrobbling in Pleroma is **deprecated**.
655 ### Requests a list of current and recent Listen activities for an account
657 * Authentication: not required
659 * Response: An array of media metadata entities.
666 "title": "Some Title",
667 "artist": "Some Artist",
668 "album": "Some Album",
670 "created_at": "2019-09-28T12:40:45.000Z"
675 ## `POST /api/v1/pleroma/scrobble`
677 Audio scrobbling in Pleroma is **deprecated**.
679 ### Creates a new Listen activity for an account
681 * Authentication: required
683 * `title`: the title of the media playing
684 * `album`: the album of the media playing [optional]
685 * `artist`: the artist of the media playing [optional]
686 * `length`: the length of the media playing [optional]
687 * Response: the newly created media metadata entity representing the Listen activity
691 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.
693 ## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji`
694 ### React to a post with a unicode emoji
696 * Authentication: required
697 * Params: `emoji`: A unicode RGI emoji or a regional indicator
698 * Response: JSON, the status.
700 ## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji`
701 ### Remove a reaction to a post with a unicode emoji
703 * Authentication: required
704 * Params: `emoji`: A unicode RGI emoji or a regional indicator
705 * Response: JSON, the status.
707 ## `GET /api/v1/pleroma/statuses/:id/reactions`
708 ### Get an object of emoji to account mappings with accounts that reacted to the post
710 * Authentication: optional
712 * 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.
716 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
717 {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
721 ## `GET /api/v1/pleroma/statuses/:id/reactions/:emoji`
722 ### Get an object of emoji to account mappings with accounts that reacted to the post for a specific emoji
724 * Authentication: optional
726 * Response: JSON, a list of emoji/account list tuples
730 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}
734 ## `POST /api/v1/pleroma/backups`
735 ### Create a user backup archive
738 * Authentication: required
745 "content_type": "application/zip",
747 "inserted_at": "2020-09-10T16:18:03.000Z",
749 "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
753 ## `GET /api/v1/pleroma/backups`
754 ### Lists user backups
757 * Authentication: not required
764 "content_type": "application/zip",
766 "inserted_at": "2020-09-10T16:18:03.000Z",
768 "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
772 ## `GET /api/oauth_tokens`
773 ### Retrieve a list of active sessions for the user
775 * Authentication: required
783 "app_name": "Pleroma FE",
785 "valid_until": "2121-11-24T15:51:08.234234"
788 "app_name": "Patron",
790 "valid_until": "2121-10-26T18:09:59.857150"
793 "app_name": "Soapbox FE",
795 "valid_until": "2121-12-25T16:52:39.692877"
800 ## `DELETE /api/oauth_tokens/:id`
801 ### Revoke a user session by its ID
803 * Authentication: required
805 * Response: HTTP 200 on success, 500 on error
807 ## `/api/v1/pleroma/settings/:app`
808 ### Gets settings for some application
810 * Authentication: `read:accounts`
812 * Response: JSON. The settings for that application, or empty object if there is none.
816 "some key": "some value"
820 ### Updates settings for some application
822 * Authentication: `write:accounts`
823 * Request body: JSON object. The object will be merged recursively with old settings. If some field is set to null, it is removed.
827 "some key": "some value",
828 "key to remove": null,
830 "some key": "some value",
831 "key to remove": null
835 * Response: JSON. Updated (merged) settings for that application.
839 "some key": "some value",
841 "some key": "some value",