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/pleroma/notifications/read`
130 ### Mark a single notification as read
132 * Authentication: required
134 * `id`: notification's id
135 * Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
137 ## `/api/v1/pleroma/accounts/:id/subscribe`
138 ### Subscribe to receive notifications for all statuses posted by a user
140 * Authentication: required
142 * `id`: account id to subscribe to
143 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
149 "followed_by": false,
152 "muting_notifications": false,
155 "domain_blocking": false,
156 "showing_reblogs": true,
161 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
162 ### Unsubscribe to stop receiving notifications from user statuses
164 * Authentication: required
166 * `id`: account id to unsubscribe from
167 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
173 "followed_by": false,
176 "muting_notifications": false,
177 "subscribing": false,
179 "domain_blocking": false,
180 "showing_reblogs": true,
185 ## `/api/v1/pleroma/accounts/:id/favourites`
186 ### Returns favorites timeline of any user
188 * Authentication: not required
190 * `id`: the id of the account for whom to return results
191 * `limit`: optional, the number of records to retrieve
192 * `since_id`: optional, returns results that are more recent than the specified id
193 * `max_id`: optional, returns results that are older than the specified id
194 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
200 "id": "9hptFmUF3ztxYh3Svg",
201 "url": "https://pleroma.example.org/users/nick2",
205 "application": {"name": "Web", "website": null},
208 "content": "This is :moominmamma: note 0",
209 "created_at": "2019-04-15T15:42:15.000Z",
212 "favourites_count": 1,
213 "id": "9hptFmVJ02khbzYJaS",
214 "in_reply_to_account_id": null,
215 "in_reply_to_id": null,
217 "media_attachments": [],
222 "content": {"text/plain": "This is :moominmamma: note 0"},
223 "conversation_id": 13679,
225 "spoiler_text": {"text/plain": "2hu"}
232 "spoiler_text": "2hu",
233 "tags": [{"name": "2hu", "url": "/tag/2hu"}],
234 "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
235 "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
236 "visibility": "public"
241 ## `/api/v1/pleroma/accounts/update_*`
242 ### Set and clear account avatar, banner, and background
244 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
245 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
246 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
248 ## `/api/v1/pleroma/accounts/confirmation_resend`
249 ### Resend confirmation email
252 * `email`: email of that needs to be verified
253 * Authentication: not required
254 * Response: 204 No Content
256 ## `/api/v1/pleroma/mascot`
257 ### Gets user mascot image
259 * Authentication: required
261 * Response: JSON. Returns a mastodon media attachment entity.
266 "url": "https://pleroma.example.org/media/abcdefg.png",
269 "mime_type": "image/png"
274 ### Updates user mascot image
276 * Authentication: required
278 * `image`: Multipart image
279 * Response: JSON. Returns a mastodon media attachment entity
280 when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
285 "url": "https://pleroma.example.org/media/abcdefg.png",
288 "mime_type": "image/png"
292 * Note: Behaves exactly the same as `POST /api/v1/upload`.
293 Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
295 ## `/api/pleroma/notification_settings`
296 ### Updates user notification settings
298 * Authentication: required
300 * `followers`: BOOLEAN field, receives notifications from followers
301 * `follows`: BOOLEAN field, receives notifications from people the user follows
302 * `remote`: BOOLEAN field, receives notifications from people on remote instances
303 * `local`: BOOLEAN field, receives notifications from people on the local instance
304 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
306 ## `/api/pleroma/healthcheck`
307 ### Healthcheck endpoint with additional system data.
309 * Authentication: not required
311 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
315 "pool_size": 0, # database connection pool
316 "active": 0, # active processes
317 "idle": 0, # idle processes
318 "memory_used": 0.00, # Memory used
319 "healthy": true # Instance state
323 # Pleroma Conversations
325 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
327 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
328 2. Pleroma Conversations statuses can be requested by Conversation id.
329 3. Pleroma Conversations can be replied to.
331 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.
333 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.
336 ## `GET /api/v1/pleroma/conversations/:id/statuses`
337 ### Timeline for a given conversation
339 * Authentication: required
340 * Params: Like other timelines
341 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
343 ## `GET /api/v1/pleroma/conversations/:id`
344 ### The conversation with the given ID.
346 * Authentication: required
348 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
350 ## `PATCH /api/v1/pleroma/conversations/:id`
351 ### Update a conversation. Used to change the set of recipients.
353 * Authentication: required
355 * `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.
356 * Response: JSON, statuses (200 - healthy, 503 unhealthy)