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 ## `/api/pleroma/emoji`
8 ### Lists the custom emoji on that server.
10 * Authentication: not required
20 "image_url": "/finmoji/128px/girlpower-128.png"
26 "image_url": "/finmoji/128px/education-128.png"
32 "image_url": "/finmoji/128px/finnishlove-128.png"
36 * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
38 ## `/api/pleroma/follow_import`
39 ### Imports your follows, for example from a Mastodon CSV file.
41 * Authentication: required
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.
47 ## `/api/pleroma/captcha`
50 * Authentication: not required
52 * Response: Provider specific JSON, the only guaranteed parameter is `type`
53 * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}`
55 ## `/api/pleroma/delete_account`
58 * Authentication: required
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."}`
64 ## `/api/pleroma/disable_account`
65 ### Disable an account
67 * Authentication: required
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."}`
73 ## `/api/account/register`
74 ### Register a new user
76 * Authentication: not required
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"}`
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,
101 "follows_you": false,
108 "no_rich_text": false,
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",
117 "delete_others_notice": false
119 "screen_name": "lain",
121 "statusnet_blocking": false,
122 "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain"
126 ## `/api/pleroma/admin/`…
127 See [Admin-API](admin_api.md)
129 ## `/api/v1/pleroma/notifications/read`
130 ### Mark notifications as read
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.
138 ## `/api/v1/pleroma/accounts/:id/subscribe`
139 ### Subscribe to receive notifications for all statuses posted by a user
141 * Authentication: required
143 * `id`: account id to subscribe to
144 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
150 "followed_by": false,
153 "muting_notifications": false,
156 "domain_blocking": false,
157 "showing_reblogs": true,
162 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
163 ### Unsubscribe to stop receiving notifications from user statuses
165 * Authentication: required
167 * `id`: account id to unsubscribe from
168 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
174 "followed_by": false,
177 "muting_notifications": false,
178 "subscribing": false,
180 "domain_blocking": false,
181 "showing_reblogs": true,
186 ## `/api/v1/pleroma/accounts/:id/favourites`
187 ### Returns favorites timeline of any user
189 * Authentication: not required
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"}`
201 "id": "9hptFmUF3ztxYh3Svg",
202 "url": "https://pleroma.example.org/users/nick2",
206 "application": {"name": "Web", "website": null},
209 "content": "This is :moominmamma: note 0",
210 "created_at": "2019-04-15T15:42:15.000Z",
213 "favourites_count": 1,
214 "id": "9hptFmVJ02khbzYJaS",
215 "in_reply_to_account_id": null,
216 "in_reply_to_id": null,
218 "media_attachments": [],
223 "content": {"text/plain": "This is :moominmamma: note 0"},
224 "conversation_id": 13679,
226 "spoiler_text": {"text/plain": "2hu"}
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"
242 ## `/api/v1/pleroma/accounts/update_*`
243 ### Set and clear account avatar, banner, and background
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
249 ## `/api/v1/pleroma/accounts/confirmation_resend`
250 ### Resend confirmation email
253 * `email`: email of that needs to be verified
254 * Authentication: not required
255 * Response: 204 No Content
257 ## `/api/v1/pleroma/mascot`
258 ### Gets user mascot image
260 * Authentication: required
262 * Response: JSON. Returns a mastodon media attachment entity.
267 "url": "https://pleroma.example.org/media/abcdefg.png",
270 "mime_type": "image/png"
275 ### Updates user mascot image
277 * Authentication: required
279 * `image`: Multipart image
280 * Response: JSON. Returns a mastodon media attachment entity
281 when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
286 "url": "https://pleroma.example.org/media/abcdefg.png",
289 "mime_type": "image/png"
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`.
296 ## `/api/pleroma/notification_settings`
297 ### Updates user notification settings
299 * Authentication: required
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"}`
308 ## `/api/pleroma/healthcheck`
309 ### Healthcheck endpoint with additional system data.
311 * Authentication: not required
313 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
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
326 ## `/api/pleroma/change_email`
327 ### Change account email
329 * Authentication: required
331 * `password`: user's password
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.
336 # Pleroma Conversations
338 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
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.
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.
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.
349 ## `GET /api/v1/pleroma/conversations/:id/statuses`
350 ### Timeline for a given conversation
352 * Authentication: required
353 * Params: Like other timelines
354 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
356 ## `GET /api/v1/pleroma/conversations/:id`
357 ### The conversation with the given ID.
359 * Authentication: required
361 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
363 ## `PATCH /api/v1/pleroma/conversations/:id`
364 ### Update a conversation. Used to change the set of recipients.
366 * Authentication: required
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)
371 ## `GET /api/v1/pleroma/conversations/read`
372 ### Marks all user's conversations as read.
374 * Authentication: required
376 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
378 ## `GET /api/pleroma/emoji/packs`
379 ### Lists the custom emoji packs on the server
381 * Authentication: not required
383 * Response: JSON, "ok" and 200 status and the JSON hashmap of "pack name" to "pack contents"
385 ## `PUT /api/pleroma/emoji/packs/:name`
386 ### Creates an empty custom emoji pack
388 * Authentication: required
390 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
392 ## `DELETE /api/pleroma/emoji/packs/:name`
393 ### Delete a custom emoji pack
395 * Authentication: required
397 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
399 ## `POST /api/pleroma/emoji/packs/:name/update_file`
400 ### Update a file in a custom emoji pack
402 * Authentication: required
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)
416 ## `POST /api/pleroma/emoji/packs/:name/update_metadata`
417 ### Updates (replaces) pack metadata
419 * Authentication: required
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)
425 ## `POST /api/pleroma/emoji/packs/download_from`
426 ### Requests the instance to download the pack from another instance
428 * Authentication: required
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
435 ## `POST /api/pleroma/emoji/packs/list_from`
436 ### Requests the instance to list the packs from another instance
438 * Authentication: required
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
444 ## `GET /api/pleroma/emoji/packs/:name/download_shared`
445 ### Requests a local pack from the instance
447 * Authentication: not required
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
452 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
453 ### Requests a list of current and recent Listen activities for an account
455 * Authentication: not required
457 * Response: An array of media metadata entities.
464 "title": "Some Title",
465 "artist": "Some Artist",
466 "album": "Some Album",
468 "created_at": "2019-09-28T12:40:45.000Z"
473 ## `POST /api/v1/pleroma/scrobble`
474 ### Creates a new Listen activity for an account
476 * Authentication: required
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
486 Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character.
488 ## `POST /api/v1/pleroma/statuses/:id/react_with_emoji`
489 ### React to a post with a unicode emoji
491 * Authentication: required
492 * Params: `emoji`: A single character unicode emoji
493 * Response: JSON, the status.
495 ## `POST /api/v1/pleroma/statuses/:id/unreact_with_emoji`
496 ### Remove a reaction to a post with a unicode emoji
498 * Authentication: required
499 * Params: `emoji`: A single character unicode emoji
500 * Response: JSON, the status.
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
505 * Authentication: optional
507 * Response: JSON, a map of emoji to account list mappings.
511 "😀" => [{"id" => "xyz.."...}, {"id" => "zyx..."}],
512 "🗡" => [{"id" => "abc..."}]