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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/pleroma/accounts/mfa`
92 #### Gets current MFA settings
94 * Authentication: required
95 * OAuth scope: `read:security`
96 * Response: JSON. Returns `{"enabled": "false", "totp": false }`
98 ## `/api/v1/pleroma/accounts/mfa/setup/totp`
99 #### Pre-setup the MFA/TOTP method
101 * Authentication: required
102 * OAuth scope: `write:security`
103 * Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]" }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}`
105 ## `/api/v1/pleroma/accounts/mfa/confirm/totp`
106 #### Confirms & enables MFA/TOTP support for user account.
108 * Authentication: required
109 * OAuth scope: `write:security`
111 * `password`: user's password
112 * `code`: token from TOTP App
113 * Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
116 ## `/api/v1/pleroma/accounts/mfa/totp`
117 #### Disables MFA/TOTP method for user account.
119 * Authentication: required
120 * OAuth scope: `write:security`
122 * `password`: user's password
123 * Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
124 * Example response: `{"error": "Invalid password."}`
126 ## `/api/v1/pleroma/accounts/mfa/backup_codes`
127 #### Generstes backup codes MFA for user account.
129 * Authentication: required
130 * OAuth scope: `write:security`
131 * Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}`
133 ## `/api/v1/pleroma/admin/`
134 See [Admin-API](admin_api.md)
136 ## `/api/v1/pleroma/notifications/read`
137 ### Mark notifications as read
139 * Authentication: required
140 * Params (mutually exclusive):
141 * `id`: a single notification id to read
142 * `max_id`: read all notifications up to this id
143 * Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
145 ## `/api/v1/pleroma/accounts/:id/subscribe`
146 ### Subscribe to receive notifications for all statuses posted by a user
148 * Authentication: required
150 * `id`: account id to subscribe to
151 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
157 "followed_by": false,
160 "muting_notifications": false,
163 "domain_blocking": false,
164 "showing_reblogs": true,
169 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
170 ### Unsubscribe to stop receiving notifications from user statuses
172 * Authentication: required
174 * `id`: account id to unsubscribe from
175 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
181 "followed_by": false,
184 "muting_notifications": false,
185 "subscribing": false,
187 "domain_blocking": false,
188 "showing_reblogs": true,
193 ## `/api/v1/pleroma/accounts/:id/favourites`
194 ### Returns favorites timeline of any user
196 * Authentication: not required
198 * `id`: the id of the account for whom to return results
199 * `limit`: optional, the number of records to retrieve
200 * `since_id`: optional, returns results that are more recent than the specified id
201 * `max_id`: optional, returns results that are older than the specified id
202 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
208 "id": "9hptFmUF3ztxYh3Svg",
209 "url": "https://pleroma.example.org/users/nick2",
213 "application": {"name": "Web", "website": null},
216 "content": "This is :moominmamma: note 0",
217 "created_at": "2019-04-15T15:42:15.000Z",
220 "favourites_count": 1,
221 "id": "9hptFmVJ02khbzYJaS",
222 "in_reply_to_account_id": null,
223 "in_reply_to_id": null,
225 "media_attachments": [],
230 "content": {"text/plain": "This is :moominmamma: note 0"},
231 "conversation_id": 13679,
233 "spoiler_text": {"text/plain": "2hu"}
240 "spoiler_text": "2hu",
241 "tags": [{"name": "2hu", "url": "/tag/2hu"}],
242 "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
243 "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
244 "visibility": "public"
249 ## `/api/v1/pleroma/accounts/update_*`
250 ### Set and clear account avatar, banner, and background
252 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
253 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
254 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
256 ## `/api/v1/pleroma/accounts/confirmation_resend`
257 ### Resend confirmation email
260 * `email`: email of that needs to be verified
261 * Authentication: not required
262 * Response: 204 No Content
264 ## `/api/v1/pleroma/mascot`
265 ### Gets user mascot image
267 * Authentication: required
269 * Response: JSON. Returns a mastodon media attachment entity.
274 "url": "https://pleroma.example.org/media/abcdefg.png",
277 "mime_type": "image/png"
282 ### Updates user mascot image
284 * Authentication: required
286 * `file`: Multipart image
287 * Response: JSON. Returns a mastodon media attachment entity
288 when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
293 "url": "https://pleroma.example.org/media/abcdefg.png",
296 "mime_type": "image/png"
300 * Note: Behaves exactly the same as `POST /api/v1/upload`.
301 Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
303 ## `/api/v1/pleroma/notification_settings`
304 ### Updates user notification settings
306 * Authentication: required
308 * `block_from_strangers`: BOOLEAN field, blocks notifications from accounts you do not follow
309 * `hide_notification_contents`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
310 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
312 ## `/api/v1/pleroma/healthcheck`
313 ### Healthcheck endpoint with additional system data.
315 * Authentication: not required
317 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
321 "pool_size": 0, # database connection pool
322 "active": 0, # active processes
323 "idle": 0, # idle processes
324 "memory_used": 0.00, # Memory used
325 "healthy": true, # Instance state
326 "job_queue_stats": {} # Job queue stats
330 ## `/api/v1/pleroma/change_email`
331 ### Change account email
333 * Authentication: required
335 * `password`: user's password
337 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
338 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
340 # Pleroma Conversations
342 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
344 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
345 2. Pleroma Conversations statuses can be requested by Conversation id.
346 3. Pleroma Conversations can be replied to.
348 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.
350 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.
352 âš Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`.
354 ## `GET /api/v1/pleroma/conversations/:id/statuses`
355 ### Timeline for a given conversation
357 * Authentication: required
358 * Params: Like other timelines
359 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
361 ## `GET /api/v1/pleroma/conversations/:id`
362 ### The conversation with the given ID.
364 * Authentication: required
366 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
368 ## `PATCH /api/v1/pleroma/conversations/:id`
369 ### Update a conversation. Used to change the set of recipients.
371 * Authentication: required
373 * `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.
374 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
376 ## `POST /api/v1/pleroma/conversations/read`
377 ### Marks all user's conversations as read.
379 * Authentication: required
381 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
383 ## `GET /api/v1/pleroma/emoji/pack?name=:name`
385 ### Get pack.json for the pack
388 * Authentication: not required
390 * `page`: page number for files (default 1)
391 * `page_size`: page size for files (default 30)
392 * Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
397 "files_count": 0, // emoji count in pack
402 ## `POST /api/v1/pleroma/emoji/pack?name=:name`
404 ### Creates an empty pack
407 * Authentication: required (admin)
410 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
412 ## `PATCH /api/v1/pleroma/emoji/pack?name=:name`
414 ### Updates (replaces) pack metadata
417 * Authentication: required (admin)
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)
430 ## `DELETE /api/v1/pleroma/emoji/pack?name=:name`
432 ### Delete a custom emoji pack
435 * Authentication: required (admin)
438 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
440 ## `GET /api/v1/pleroma/emoji/packs/import`
442 ### Imports packs from filesystem
445 * Authentication: required (admin)
447 * Response: JSON, returns a list of imported packs.
449 ## `GET /api/v1/pleroma/emoji/packs/remote`
451 ### Make request to another instance for packs list
454 * Authentication: required (admin)
456 * `url`: url of the instance to get packs from
457 * `page`: page number for packs (default 1)
458 * `page_size`: page size for packs (default 50)
459 * Response: JSON with the pack list, hashmap with pack name and pack contents
461 ## `POST /api/v1/pleroma/emoji/packs/download`
463 ### Download pack from another instance
466 * Authentication: required (admin)
468 * `url`: url of the instance to download from
469 * `name`: pack to download from that instance
470 * `as`: (*optional*) name how to save pack
471 * Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
472 errors downloading the pack
474 ## `POST /api/v1/pleroma/emoji/packs/files?name=:name`
476 ### Add new file to the pack
479 * Authentication: required (admin)
482 * `file`: file needs to be uploaded with the multipart request or link to remote file.
483 * `shortcode`: (*optional*) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.
484 * `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename.
485 * Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
487 ## `PATCH /api/v1/pleroma/emoji/packs/files?name=:name`
489 ### Update emoji file from pack
492 * Authentication: required (admin)
495 * `shortcode`: emoji file shortcode
496 * `new_shortcode`: new emoji file shortcode
497 * `new_filename`: new filename for emoji file
498 * `force`: (*optional*) with true value to overwrite existing emoji with new shortcode
499 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
501 ## `DELETE /api/v1/pleroma/emoji/packs/files?name=:name`
503 ### Delete emoji file from pack
506 * Authentication: required (admin)
509 * `shortcode`: emoji file shortcode
510 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
512 ## `GET /api/v1/pleroma/emoji/packs`
514 ### Lists local custom emoji packs
517 * Authentication: not required
519 * `page`: page number for packs (default 1)
520 * `page_size`: page size for packs (default 50)
521 * Response: `packs` key with JSON hashmap of pack name to pack contents and `count` key for count of packs.
526 "pack_name": {...}, // pack contents
529 "count": 0 // packs count
533 ## `GET /api/v1/pleroma/emoji/packs/archive?name=:name`
535 ### Requests a local pack archive from the instance
538 * Authentication: not required
541 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
542 404 if the pack does not exist
544 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
545 ### Requests a list of current and recent Listen activities for an account
547 * Authentication: not required
549 * Response: An array of media metadata entities.
556 "title": "Some Title",
557 "artist": "Some Artist",
558 "album": "Some Album",
560 "created_at": "2019-09-28T12:40:45.000Z"
565 ## `POST /api/v1/pleroma/scrobble`
566 ### Creates a new Listen activity for an account
568 * Authentication: required
570 * `title`: the title of the media playing
571 * `album`: the album of the media playing [optional]
572 * `artist`: the artist of the media playing [optional]
573 * `length`: the length of the media playing [optional]
574 * Response: the newly created media metadata entity representing the Listen activity
578 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.
580 ## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji`
581 ### React to a post with a unicode emoji
583 * Authentication: required
584 * Params: `emoji`: A unicode RGI emoji or a regional indicator
585 * Response: JSON, the status.
587 ## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji`
588 ### Remove a reaction to a post with a unicode emoji
590 * Authentication: required
591 * Params: `emoji`: A unicode RGI emoji or a regional indicator
592 * Response: JSON, the status.
594 ## `GET /api/v1/pleroma/statuses/:id/reactions`
595 ### Get an object of emoji to account mappings with accounts that reacted to the post
597 * Authentication: optional
599 * 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.
603 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
604 {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
608 ## `GET /api/v1/pleroma/statuses/:id/reactions/:emoji`
609 ### Get an object of emoji to account mappings with accounts that reacted to the post for a specific emoji
611 * Authentication: optional
613 * Response: JSON, a list of emoji/account list tuples
617 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}
621 ## `POST /api/v1/pleroma/backups`
622 ### Create a user backup archive
625 * Authentication: required
632 "content_type": "application/zip",
634 "inserted_at": "2020-09-10T16:18:03.000Z",
636 "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"
640 ## `GET /api/v1/pleroma/backups`
641 ### Lists user backups
644 * Authentication: not required
651 "content_type": "application/zip",
653 "inserted_at": "2020-09-10T16:18:03.000Z",
655 "url": "https://example.com/media/backups/archive-foobar-20200910T161803-QUhx6VYDRQ2wfV0SdA2Pfj_2CLM_ATUlw-D5l5TJf4Q.zip"