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