Merge branch 'feature/1739-account-endpoints' into 'develop'
[akkoma] / docs / API / pleroma_api.md
1 # Pleroma API
2
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).
4
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`.
6
7 ## `/api/pleroma/emoji`
8 ### Lists the custom emoji on that server.
9 * Method: `GET`
10 * Authentication: not required
11 * Params: none
12 * Response: JSON
13 * Example response:
14 ```json
15 {
16 "girlpower": {
17 "tags": [
18 "Finmoji"
19 ],
20 "image_url": "/finmoji/128px/girlpower-128.png"
21 },
22 "education": {
23 "tags": [
24 "Finmoji"
25 ],
26 "image_url": "/finmoji/128px/education-128.png"
27 },
28 "finnishlove": {
29 "tags": [
30 "Finmoji"
31 ],
32 "image_url": "/finmoji/128px/finnishlove-128.png"
33 }
34 }
35 ```
36 * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
37
38 ## `/api/pleroma/follow_import`
39 ### Imports your follows, for example from a Mastodon CSV file.
40 * Method: `POST`
41 * Authentication: required
42 * Params:
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.
46
47 ## `/api/pleroma/captcha`
48 ### Get a new captcha
49 * Method: `GET`
50 * Authentication: not required
51 * Params: none
52 * Response: Provider specific JSON, the only guaranteed parameter is `type`
53 * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}`
54
55 ## `/api/pleroma/delete_account`
56 ### Delete an account
57 * Method `POST`
58 * Authentication: required
59 * Params:
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."}`
63
64 ## `/api/pleroma/disable_account`
65 ### Disable an account
66 * Method `POST`
67 * Authentication: required
68 * Params:
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."}`
72
73 ## `/api/pleroma/accounts/mfa`
74 #### Gets current MFA settings
75 * method: `GET`
76 * Authentication: required
77 * OAuth scope: `read:security`
78 * Response: JSON. Returns `{"enabled": "false", "totp": false }`
79
80 ## `/api/pleroma/accounts/mfa/setup/totp`
81 #### Pre-setup the MFA/TOTP method
82 * method: `GET`
83 * Authentication: required
84 * OAuth scope: `write:security`
85 * Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]" }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}`
86
87 ## `/api/pleroma/accounts/mfa/confirm/totp`
88 #### Confirms & enables MFA/TOTP support for user account.
89 * method: `POST`
90 * Authentication: required
91 * OAuth scope: `write:security`
92 * Params:
93 * `password`: user's password
94 * `code`: token from TOTP App
95 * Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
96
97
98 ## `/api/pleroma/accounts/mfa/totp`
99 #### Disables MFA/TOTP method for user account.
100 * method: `DELETE`
101 * Authentication: required
102 * OAuth scope: `write:security`
103 * Params:
104 * `password`: user's password
105 * Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
106 * Example response: `{"error": "Invalid password."}`
107
108 ## `/api/pleroma/accounts/mfa/backup_codes`
109 #### Generstes backup codes MFA for user account.
110 * method: `GET`
111 * Authentication: required
112 * OAuth scope: `write:security`
113 * Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}`
114
115 ## `/api/pleroma/admin/`
116 See [Admin-API](admin_api.md)
117
118 ## `/api/v1/pleroma/notifications/read`
119 ### Mark notifications as read
120 * Method `POST`
121 * Authentication: required
122 * Params (mutually exclusive):
123 * `id`: a single notification id to read
124 * `max_id`: read all notifications up to this id
125 * Response: Notification entity/Array of Notification entities that were read. In case of `max_id`, only the first 80 read notifications will be returned.
126
127 ## `/api/v1/pleroma/accounts/:id/subscribe`
128 ### Subscribe to receive notifications for all statuses posted by a user
129 * Method `POST`
130 * Authentication: required
131 * Params:
132 * `id`: account id to subscribe to
133 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
134 * Example response:
135 ```json
136 {
137 "id": "abcdefg",
138 "following": true,
139 "followed_by": false,
140 "blocking": false,
141 "muting": false,
142 "muting_notifications": false,
143 "subscribing": true,
144 "requested": false,
145 "domain_blocking": false,
146 "showing_reblogs": true,
147 "endorsed": false
148 }
149 ```
150
151 ## `/api/v1/pleroma/accounts/:id/unsubscribe`
152 ### Unsubscribe to stop receiving notifications from user statuses
153 * Method `POST`
154 * Authentication: required
155 * Params:
156 * `id`: account id to unsubscribe from
157 * Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}`
158 * Example response:
159 ```json
160 {
161 "id": "abcdefg",
162 "following": true,
163 "followed_by": false,
164 "blocking": false,
165 "muting": false,
166 "muting_notifications": false,
167 "subscribing": false,
168 "requested": false,
169 "domain_blocking": false,
170 "showing_reblogs": true,
171 "endorsed": false
172 }
173 ```
174
175 ## `/api/v1/pleroma/accounts/:id/favourites`
176 ### Returns favorites timeline of any user
177 * Method `GET`
178 * Authentication: not required
179 * Params:
180 * `id`: the id of the account for whom to return results
181 * `limit`: optional, the number of records to retrieve
182 * `since_id`: optional, returns results that are more recent than the specified id
183 * `max_id`: optional, returns results that are older than the specified id
184 * Response: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}`
185 * Example response:
186 ```json
187 [
188 {
189 "account": {
190 "id": "9hptFmUF3ztxYh3Svg",
191 "url": "https://pleroma.example.org/users/nick2",
192 "username": "nick2",
193 ...
194 },
195 "application": {"name": "Web", "website": null},
196 "bookmarked": false,
197 "card": null,
198 "content": "This is :moominmamma: note 0",
199 "created_at": "2019-04-15T15:42:15.000Z",
200 "emojis": [],
201 "favourited": false,
202 "favourites_count": 1,
203 "id": "9hptFmVJ02khbzYJaS",
204 "in_reply_to_account_id": null,
205 "in_reply_to_id": null,
206 "language": null,
207 "media_attachments": [],
208 "mentions": [],
209 "muted": false,
210 "pinned": false,
211 "pleroma": {
212 "content": {"text/plain": "This is :moominmamma: note 0"},
213 "conversation_id": 13679,
214 "local": true,
215 "spoiler_text": {"text/plain": "2hu"}
216 },
217 "reblog": null,
218 "reblogged": false,
219 "reblogs_count": 0,
220 "replies_count": 0,
221 "sensitive": false,
222 "spoiler_text": "2hu",
223 "tags": [{"name": "2hu", "url": "/tag/2hu"}],
224 "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984",
225 "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS",
226 "visibility": "public"
227 }
228 ]
229 ```
230
231 ## `/api/v1/pleroma/accounts/update_*`
232 ### Set and clear account avatar, banner, and background
233
234 - PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image
235 - PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image
236 - PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image
237
238 ## `/api/v1/pleroma/accounts/confirmation_resend`
239 ### Resend confirmation email
240 * Method `POST`
241 * Params:
242 * `email`: email of that needs to be verified
243 * Authentication: not required
244 * Response: 204 No Content
245
246 ## `/api/v1/pleroma/mascot`
247 ### Gets user mascot image
248 * Method `GET`
249 * Authentication: required
250
251 * Response: JSON. Returns a mastodon media attachment entity.
252 * Example response:
253 ```json
254 {
255 "id": "abcdefg",
256 "url": "https://pleroma.example.org/media/abcdefg.png",
257 "type": "image",
258 "pleroma": {
259 "mime_type": "image/png"
260 }
261 }
262 ```
263
264 ### Updates user mascot image
265 * Method `PUT`
266 * Authentication: required
267 * Params:
268 * `file`: Multipart image
269 * Response: JSON. Returns a mastodon media attachment entity
270 when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
271 * Example response:
272 ```json
273 {
274 "id": "abcdefg",
275 "url": "https://pleroma.example.org/media/abcdefg.png",
276 "type": "image",
277 "pleroma": {
278 "mime_type": "image/png"
279 }
280 }
281 ```
282 * Note: Behaves exactly the same as `POST /api/v1/upload`.
283 Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
284
285 ## `/api/pleroma/notification_settings`
286 ### Updates user notification settings
287 * Method `PUT`
288 * Authentication: required
289 * Params:
290 * `followers`: BOOLEAN field, receives notifications from followers
291 * `follows`: BOOLEAN field, receives notifications from people the user follows
292 * `remote`: BOOLEAN field, receives notifications from people on remote instances
293 * `local`: BOOLEAN field, receives notifications from people on the local instance
294 * `privacy_option`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification.
295 * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
296
297 ## `/api/pleroma/healthcheck`
298 ### Healthcheck endpoint with additional system data.
299 * Method `GET`
300 * Authentication: not required
301 * Params: none
302 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
303 * Example response:
304 ```json
305 {
306 "pool_size": 0, # database connection pool
307 "active": 0, # active processes
308 "idle": 0, # idle processes
309 "memory_used": 0.00, # Memory used
310 "healthy": true, # Instance state
311 "job_queue_stats": {} # Job queue stats
312 }
313 ```
314
315 ## `/api/pleroma/change_email`
316 ### Change account email
317 * Method `POST`
318 * Authentication: required
319 * Params:
320 * `password`: user's password
321 * `email`: new email
322 * Response: JSON. Returns `{"status": "success"}` if the change was successful, `{"error": "[error message]"}` otherwise
323 * Note: Currently, Mastodon has no API for changing email. If they add it in future it might be incompatible with Pleroma.
324
325 # Pleroma Conversations
326
327 Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints:
328
329 1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user.
330 2. Pleroma Conversations statuses can be requested by Conversation id.
331 3. Pleroma Conversations can be replied to.
332
333 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.
334
335 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
337 âš  Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`.
338
339 ## `GET /api/v1/pleroma/conversations/:id/statuses`
340 ### Timeline for a given conversation
341 * Method `GET`
342 * Authentication: required
343 * Params: Like other timelines
344 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
345
346 ## `GET /api/v1/pleroma/conversations/:id`
347 ### The conversation with the given ID.
348 * Method `GET`
349 * Authentication: required
350 * Params: None
351 * Response: JSON, statuses (200 - healthy, 503 unhealthy).
352
353 ## `PATCH /api/v1/pleroma/conversations/:id`
354 ### Update a conversation. Used to change the set of recipients.
355 * Method `PATCH`
356 * Authentication: required
357 * Params:
358 * `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.
359 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
360
361 ## `POST /api/v1/pleroma/conversations/read`
362 ### Marks all user's conversations as read.
363 * Method `POST`
364 * Authentication: required
365 * Params: None
366 * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
367
368 ## `GET /api/pleroma/emoji/packs/import`
369 ### Imports packs from filesystem
370 * Method `GET`
371 * Authentication: required
372 * Params: None
373 * Response: JSON, returns a list of imported packs.
374
375 ## `GET /api/pleroma/emoji/packs/remote`
376 ### Make request to another instance for packs list
377 * Method `GET`
378 * Authentication: required
379 * Params:
380 * `url`: url of the instance to get packs from
381 * Response: JSON with the pack list, hashmap with pack name and pack contents
382
383 ## `POST /api/pleroma/emoji/packs/download`
384 ### Download pack from another instance
385 * Method `POST`
386 * Authentication: required
387 * Params:
388 * `url`: url of the instance to download from
389 * `name`: pack to download from that instance
390 * `as`: (*optional*) name how to save pack
391 * Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
392 errors downloading the pack
393
394 ## `POST /api/pleroma/emoji/packs/:name`
395 ### Creates an empty pack
396 * Method `POST`
397 * Authentication: required
398 * Params: None
399 * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
400
401 ## `PATCH /api/pleroma/emoji/packs/:name`
402 ### Updates (replaces) pack metadata
403 * Method `PATCH`
404 * Authentication: required
405 * Params:
406 * `metadata`: metadata to replace the old one
407 * `license`: Pack license
408 * `homepage`: Pack home page url
409 * `description`: Pack description
410 * `fallback-src`: Fallback url to download pack from
411 * `fallback-src-sha256`: SHA256 encoded for fallback pack archive
412 * `share-files`: is pack allowed for sharing (boolean)
413 * Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a
414 problem with the new metadata (the error is specified in the "error" part of the response JSON)
415
416 ## `DELETE /api/pleroma/emoji/packs/:name`
417 ### Delete a custom emoji pack
418 * Method `DELETE`
419 * Authentication: required
420 * Params: None
421 * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
422
423 ## `POST /api/pleroma/emoji/packs/:name/files`
424 ### Add new file to the pack
425 * Method `POST`
426 * Authentication: required
427 * Params:
428 * `file`: file needs to be uploaded with the multipart request or link to remote file.
429 * `shortcode`: (*optional*) shortcode for new emoji, must be unique for all emoji. If not sended, shortcode will be taken from original filename.
430 * `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename.
431 * Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
432
433 ## `PATCH /api/pleroma/emoji/packs/:name/files`
434 ### Update emoji file from pack
435 * Method `PATCH`
436 * Authentication: required
437 * Params:
438 * `shortcode`: emoji file shortcode
439 * `new_shortcode`: new emoji file shortcode
440 * `new_filename`: new filename for emoji file
441 * `force`: (*optional*) with true value to overwrite existing emoji with new shortcode
442 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
443
444 ## `DELETE /api/pleroma/emoji/packs/:name/files`
445 ### Delete emoji file from pack
446 * Method `DELETE`
447 * Authentication: required
448 * Params:
449 * `shortcode`: emoji file shortcode
450 * Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
451
452 ## `GET /api/pleroma/emoji/packs`
453
454 ### Lists local custom emoji packs
455
456 * Method `GET`
457 * Authentication: not required
458 * Params:
459 * `page`: page number for packs (default 1)
460 * `page_size`: page size for packs (default 50)
461 * Response: `packs` key with JSON hashmap of pack name to pack contents and `count` key for count of packs.
462
463 ```json
464 {
465 "packs": {
466 "pack_name": {...}, // pack contents
467 ...
468 },
469 "count": 0 // packs count
470 }
471 ```
472
473 ## `GET /api/pleroma/emoji/packs/:name`
474
475 ### Get pack.json for the pack
476
477 * Method `GET`
478 * Authentication: not required
479 * Params:
480 * `page`: page number for files (default 1)
481 * `page_size`: page size for files (default 30)
482 * Response: JSON, pack json with `files`, `files_count` and `pack` keys with 200 status or 404 if the pack does not exist.
483
484 ```json
485 {
486 "files": {...},
487 "files_count": 0, // emoji count in pack
488 "pack": {...}
489 }
490 ```
491
492 ## `GET /api/pleroma/emoji/packs/:name/archive`
493 ### Requests a local pack archive from the instance
494 * Method `GET`
495 * Authentication: not required
496 * Params: None
497 * Response: the archive of the pack with a 200 status code, 403 if the pack is not set as shared,
498 404 if the pack does not exist
499
500 ## `GET /api/v1/pleroma/accounts/:id/scrobbles`
501 ### Requests a list of current and recent Listen activities for an account
502 * Method `GET`
503 * Authentication: not required
504 * Params: None
505 * Response: An array of media metadata entities.
506 * Example response:
507 ```json
508 [
509 {
510 "account": {...},
511 "id": "1234",
512 "title": "Some Title",
513 "artist": "Some Artist",
514 "album": "Some Album",
515 "length": 180000,
516 "created_at": "2019-09-28T12:40:45.000Z"
517 }
518 ]
519 ```
520
521 ## `POST /api/v1/pleroma/scrobble`
522 ### Creates a new Listen activity for an account
523 * Method `POST`
524 * Authentication: required
525 * Params:
526 * `title`: the title of the media playing
527 * `album`: the album of the media playing [optional]
528 * `artist`: the artist of the media playing [optional]
529 * `length`: the length of the media playing [optional]
530 * Response: the newly created media metadata entity representing the Listen activity
531
532 # Emoji Reactions
533
534 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.
535
536 ## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji`
537 ### React to a post with a unicode emoji
538 * Method: `PUT`
539 * Authentication: required
540 * Params: `emoji`: A single character unicode emoji
541 * Response: JSON, the status.
542
543 ## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji`
544 ### Remove a reaction to a post with a unicode emoji
545 * Method: `DELETE`
546 * Authentication: required
547 * Params: `emoji`: A single character unicode emoji
548 * Response: JSON, the status.
549
550 ## `GET /api/v1/pleroma/statuses/:id/reactions`
551 ### Get an object of emoji to account mappings with accounts that reacted to the post
552 * Method: `GET`
553 * Authentication: optional
554 * Params: None
555 * 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.
556 * Example Response:
557 ```json
558 [
559 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]},
560 {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]}
561 ]
562 ```
563
564 ## `GET /api/v1/pleroma/statuses/:id/reactions/:emoji`
565 ### Get an object of emoji to account mappings with accounts that reacted to the post for a specific emoji
566 * Method: `GET`
567 * Authentication: optional
568 * Params: None
569 * Response: JSON, a list of emoji/account list tuples
570 * Example Response:
571 ```json
572 [
573 {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}
574 ]
575 ```