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/flavour/:flavour`
131 * Authentication: required
132 * Response: JSON string. Returns the user flavour or the default one on success, otherwise returns `{"error": "error_msg"}`
133 * Example response: "glitch"
134 * Note: This is intended to be used only by mastofe
136 ## `/api/v1/pleroma/flavour`
138 * Authentication: required
139 * Response: JSON string. Returns the user flavour or the default one.
140 * Example response: "glitch"
141 * Note: This is intended to be used only by mastofe
143 ## `/api/pleroma/notifications/read`
144 ### Mark a single notification as read
146 * Authentication: required
148 * `id`: notification's id
149 * Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
151 ## `/api/v1/pleroma/accounts/:id/subscribe`
152 ### Subscribe to receive notifications for all statuses posted by a user
154 * Authentication: required
156 * `id`: account id to subscribe to
157 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
163 "followed_by": false,
166 "muting_notifications": false,
169 "domain_blocking": false,
170 "showing_reblogs": true,
175 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
176 ### Unsubscribe to stop receiving notifications from user statuses
178 * Authentication: required
180 * `id`: account id to unsubscribe from
181 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
187 "followed_by": false,
190 "muting_notifications": false,
191 "subscribing": false,
193 "domain_blocking": false,
194 "showing_reblogs": true,
199 ## `/api/v1/pleroma/accounts/:id/favourites`
200 ### Returns favorites timeline of any user
202 * Authentication: not required
204 * `id`: the id of the account for whom to return results
205 * `limit`: optional, the number of records to retrieve
206 * `since_id`: optional, returns results that are more recent than the specified id
207 * `max_id`: optional, returns results that are older than the specified id
208 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
214 "id": "9hptFmUF3ztxYh3Svg",
215 "url": "https://pleroma.example.org/users/nick2",
219 "application": {"name": "Web", "website": null},
222 "content": "This is :moominmamma: note 0",
223 "created_at": "2019-04-15T15:42:15.000Z",
226 "favourites_count": 1,
227 "id": "9hptFmVJ02khbzYJaS",
228 "in_reply_to_account_id": null,
229 "in_reply_to_id": null,
231 "media_attachments": [],
236 "content": {"text/plain": "This is :moominmamma: note 0"},
237 "conversation_id": 13679,
239 "spoiler_text": {"text/plain": "2hu"}
246 "spoiler_text": "2hu",
247 "tags": [{"name": "2hu", "url": "/tag/2hu"}],
248 "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
249 "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
250 "visibility": "public"
255 ## `/api/pleroma/notification_settings`
256 ### Updates user notification settings
258 * Authentication: required
260 * `followers`: BOOLEAN field, receives notifications from followers
261 * `follows`: BOOLEAN field, receives notifications from people the user follows
262 * `remote`: BOOLEAN field, receives notifications from people on remote instances
263 * `local`: BOOLEAN field, receives notifications from people on the local instance
264 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
266 ## `/api/pleroma/healthcheck`
267 ### Healthcheck endpoint with additional system data.
269 * Authentication: not required
271 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
275 "pool_size": 0, # database connection pool
276 "active": 0, # active processes
277 "idle": 0, # idle processes
278 "memory_used": 0.00, # Memory used
279 "healthy": true # Instance state