Docs: AdminAPI chat moderation
[akkoma] / docs / API / admin_api.md
1 # Admin API
2
3 Authentication is required and the user must be an admin.
4
5 Configuration options:
6
7 * `[:auth, :enforce_oauth_admin_scope_usage]` — OAuth admin scope requirement toggle.
8 If `true`, admin actions explicitly demand admin OAuth scope(s) presence in OAuth token (client app must support admin scopes).
9 If `false` and token doesn't have admin scope(s), `is_admin` user flag grants access to admin-specific actions.
10 Note that client app needs to explicitly support admin scopes and request them when obtaining auth token.
11
12 ## `GET /api/pleroma/admin/users`
13
14 ### List users
15
16 - Query Params:
17 - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
18 - *optional* `filters`: **string** comma-separated string of filters:
19 - `local`: only local users
20 - `external`: only external users
21 - `active`: only active users
22 - `need_approval`: only unapproved users
23 - `deactivated`: only deactivated users
24 - `is_admin`: users with admin role
25 - `is_moderator`: users with moderator role
26 - *optional* `page`: **integer** page number
27 - *optional* `page_size`: **integer** number of users per page (default is `50`)
28 - *optional* `tags`: **[string]** tags list
29 - *optional* `name`: **string** user display name
30 - *optional* `email`: **string** user email
31 - Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com`
32 - Response:
33
34 ```json
35 {
36 "page_size": integer,
37 "count": integer,
38 "users": [
39 {
40 "deactivated": bool,
41 "id": integer,
42 "nickname": string,
43 "roles": {
44 "admin": bool,
45 "moderator": bool
46 },
47 "local": bool,
48 "tags": array,
49 "avatar": string,
50 "display_name": string,
51 "confirmation_pending": bool,
52 "approval_pending": bool,
53 "registration_reason": string,
54 },
55 ...
56 ]
57 }
58 ```
59
60 ## DEPRECATED `DELETE /api/pleroma/admin/users`
61
62 ### Remove a user
63
64 - Params:
65 - `nickname`
66 - Response: User’s nickname
67
68 ## `DELETE /api/pleroma/admin/users`
69
70 ### Remove a user
71
72 - Params:
73 - `nicknames`
74 - Response: Array of user nicknames
75
76 ### Create a user
77
78 - Method: `POST`
79 - Params:
80 `users`: [
81 {
82 `nickname`,
83 `email`,
84 `password`
85 }
86 ]
87 - Response: User’s nickname
88
89 ## `POST /api/pleroma/admin/users/follow`
90
91 ### Make a user follow another user
92
93 - Params:
94 - `follower`: The nickname of the follower
95 - `followed`: The nickname of the followed
96 - Response:
97 - "ok"
98
99 ## `POST /api/pleroma/admin/users/unfollow`
100
101 ### Make a user unfollow another user
102
103 - Params:
104 - `follower`: The nickname of the follower
105 - `followed`: The nickname of the followed
106 - Response:
107 - "ok"
108
109 ## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation`
110
111 ### Toggle user activation
112
113 - Params:
114 - `nickname`
115 - Response: User’s object
116
117 ```json
118 {
119 "deactivated": bool,
120 "id": integer,
121 "nickname": string
122 }
123 ```
124
125 ## `PUT /api/pleroma/admin/users/tag`
126
127 ### Tag a list of users
128
129 - Params:
130 - `nicknames` (array)
131 - `tags` (array)
132
133 ## `DELETE /api/pleroma/admin/users/tag`
134
135 ### Untag a list of users
136
137 - Params:
138 - `nicknames` (array)
139 - `tags` (array)
140
141 ## `GET /api/pleroma/admin/users/:nickname/permission_group`
142
143 ### Get user user permission groups membership
144
145 - Params: none
146 - Response:
147
148 ```json
149 {
150 "is_moderator": bool,
151 "is_admin": bool
152 }
153 ```
154
155 ## `GET /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
156
157 Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
158
159 ### Get user user permission groups membership per permission group
160
161 - Params: none
162 - Response:
163
164 ```json
165 {
166 "is_moderator": bool,
167 "is_admin": bool
168 }
169 ```
170
171 ## DEPRECATED `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
172
173 ### Add user to permission group
174
175 - Params: none
176 - Response:
177 - On failure: `{"error": "…"}`
178 - On success: JSON of the user
179
180 ## `POST /api/pleroma/admin/users/permission_group/:permission_group`
181
182 ### Add users to permission group
183
184 - Params:
185 - `nicknames`: nicknames array
186 - Response:
187 - On failure: `{"error": "…"}`
188 - On success: JSON of the user
189
190 ## DEPRECATED `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
191
192 ## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
193
194 ### Remove user from permission group
195
196 - Params: none
197 - Response:
198 - On failure: `{"error": "…"}`
199 - On success: JSON of the user
200 - Note: An admin cannot revoke their own admin status.
201
202 ## `DELETE /api/pleroma/admin/users/permission_group/:permission_group`
203
204 ### Remove users from permission group
205
206 - Params:
207 - `nicknames`: nicknames array
208 - Response:
209 - On failure: `{"error": "…"}`
210 - On success: JSON of the user
211 - Note: An admin cannot revoke their own admin status.
212
213 ## `PATCH /api/pleroma/admin/users/activate`
214
215 ### Activate user
216
217 - Params:
218 - `nicknames`: nicknames array
219 - Response:
220
221 ```json
222 {
223 users: [
224 {
225 // user object
226 }
227 ]
228 }
229 ```
230
231 ## `PATCH /api/pleroma/admin/users/deactivate`
232
233 ### Deactivate user
234
235 - Params:
236 - `nicknames`: nicknames array
237 - Response:
238
239 ```json
240 {
241 users: [
242 {
243 // user object
244 }
245 ]
246 }
247 ```
248
249 ## `PATCH /api/pleroma/admin/users/approve`
250
251 ### Approve user
252
253 - Params:
254 - `nicknames`: nicknames array
255 - Response:
256
257 ```json
258 {
259 users: [
260 {
261 // user object
262 }
263 ]
264 }
265 ```
266
267 ## `GET /api/pleroma/admin/users/:nickname_or_id`
268
269 ### Retrive the details of a user
270
271 - Params:
272 - `nickname` or `id`
273 - Response:
274 - On failure: `Not found`
275 - On success: JSON of the user
276
277 ## `GET /api/pleroma/admin/users/:nickname_or_id/statuses`
278
279 ### Retrive user's latest statuses
280
281 - Params:
282 - `nickname` or `id`
283 - *optional* `page_size`: number of statuses to return (default is `20`)
284 - *optional* `godmode`: `true`/`false` – allows to see private statuses
285 - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
286 - Response:
287 - On failure: `Not found`
288 - On success: JSON array of user's latest statuses
289
290 ## `GET /api/pleroma/admin/instances/:instance/statuses`
291
292 ### Retrive instance's latest statuses
293
294 - Params:
295 - `instance`: instance name
296 - *optional* `page_size`: number of statuses to return (default is `20`)
297 - *optional* `godmode`: `true`/`false` – allows to see private statuses
298 - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
299 - Response:
300 - On failure: `Not found`
301 - On success: JSON array of instance's latest statuses
302
303 ## `GET /api/pleroma/admin/statuses`
304
305 ### Retrives all latest statuses
306
307 - Params:
308 - *optional* `page_size`: number of statuses to return (default is `20`)
309 - *optional* `local_only`: excludes remote statuses
310 - *optional* `godmode`: `true`/`false` – allows to see private statuses
311 - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
312 - Response:
313 - On failure: `Not found`
314 - On success: JSON array of user's latest statuses
315
316 ## `GET /api/pleroma/admin/relay`
317
318 ### List Relays
319
320 Params: none
321 Response:
322
323 * On success: JSON array of relays
324
325 ```json
326 [
327 {"actor": "https://example.com/relay", "followed_back": true},
328 {"actor": "https://example2.com/relay", "followed_back": false}
329 ]
330 ```
331
332 ## `POST /api/pleroma/admin/relay`
333
334 ### Follow a Relay
335
336 Params:
337
338 * `relay_url`
339
340 Response:
341
342 * On success: relay json object
343
344 ```json
345 {"actor": "https://example.com/relay", "followed_back": true}
346 ```
347
348 ## `DELETE /api/pleroma/admin/relay`
349
350 ### Unfollow a Relay
351
352 Params:
353
354 * `relay_url`
355
356 Response:
357
358 * On success: URL of the unfollowed relay
359
360 ```json
361 {"https://example.com/relay"}
362 ```
363
364 ## `POST /api/pleroma/admin/users/invite_token`
365
366 ### Create an account registration invite token
367
368 - Params:
369 - *optional* `max_use` (integer)
370 - *optional* `expires_at` (date string e.g. "2019-04-07")
371 - Response:
372
373 ```json
374 {
375 "id": integer,
376 "token": string,
377 "used": boolean,
378 "expires_at": date,
379 "uses": integer,
380 "max_use": integer,
381 "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
382 }
383 ```
384
385 ## `GET /api/pleroma/admin/users/invites`
386
387 ### Get a list of generated invites
388
389 - Params: none
390 - Response:
391
392 ```json
393 {
394
395 "invites": [
396 {
397 "id": integer,
398 "token": string,
399 "used": boolean,
400 "expires_at": date,
401 "uses": integer,
402 "max_use": integer,
403 "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
404 },
405 ...
406 ]
407 }
408 ```
409
410 ## `POST /api/pleroma/admin/users/revoke_invite`
411
412 ### Revoke invite by token
413
414 - Params:
415 - `token`
416 - Response:
417
418 ```json
419 {
420 "id": integer,
421 "token": string,
422 "used": boolean,
423 "expires_at": date,
424 "uses": integer,
425 "max_use": integer,
426 "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
427
428 }
429 ```
430
431 ## `POST /api/pleroma/admin/users/email_invite`
432
433 ### Sends registration invite via email
434
435 - Params:
436 - `email`
437 - `name`, optional
438
439 - Response:
440 - On success: `204`, empty response
441 - On failure:
442 - 400 Bad Request, JSON:
443
444 ```json
445 [
446 {
447 "error": "Appropriate error message here"
448 }
449 ]
450 ```
451
452 ## `GET /api/pleroma/admin/users/:nickname/password_reset`
453
454 ### Get a password reset token for a given nickname
455
456
457 - Params: none
458 - Response:
459
460 ```json
461 {
462 "token": "base64 reset token",
463 "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token"
464 }
465 ```
466
467 ## `PATCH /api/pleroma/admin/users/force_password_reset`
468
469 ### Force passord reset for a user with a given nickname
470
471 - Params:
472 - `nicknames`
473 - Response: none (code `204`)
474
475 ## PUT `/api/pleroma/admin/users/disable_mfa`
476
477 ### Disable mfa for user's account.
478
479 - Params:
480 - `nickname`
481 - Response: User’s nickname
482
483 ## `GET /api/pleroma/admin/users/:nickname/credentials`
484
485 ### Get the user's email, password, display and settings-related fields
486
487 - Params:
488 - `nickname`
489
490 - Response:
491
492 ```json
493 {
494 "actor_type": "Person",
495 "allow_following_move": true,
496 "avatar": "https://pleroma.social/media/7e8e7508fd545ef580549b6881d80ec0ff2c81ed9ad37b9bdbbdf0e0d030159d.jpg",
497 "background": "https://pleroma.social/media/4de34c0bd10970d02cbdef8972bef0ebbf55f43cadc449554d4396156162fe9a.jpg",
498 "banner": "https://pleroma.social/media/8d92ba2bd244b613520abf557dd448adcd30f5587022813ee9dd068945986946.jpg",
499 "bio": "bio",
500 "default_scope": "public",
501 "discoverable": false,
502 "email": "user@example.com",
503 "fields": [
504 {
505 "name": "example",
506 "value": "<a href=\"https://example.com\" rel=\"ugc\">https://example.com</a>"
507 }
508 ],
509 "hide_favorites": false,
510 "hide_followers": false,
511 "hide_followers_count": false,
512 "hide_follows": false,
513 "hide_follows_count": false,
514 "id": "9oouHaEEUR54hls968",
515 "locked": true,
516 "name": "user",
517 "no_rich_text": true,
518 "pleroma_settings_store": {},
519 "raw_fields": [
520 {
521 "id": 1,
522 "name": "example",
523 "value": "https://example.com"
524 },
525 ],
526 "show_role": true,
527 "skip_thread_containment": false
528 }
529 ```
530
531 ## `PATCH /api/pleroma/admin/users/:nickname/credentials`
532
533 ### Change the user's email, password, display and settings-related fields
534
535 * Params:
536 * `email`
537 * `password`
538 * `name`
539 * `bio`
540 * `avatar`
541 * `locked`
542 * `no_rich_text`
543 * `default_scope`
544 * `banner`
545 * `hide_follows`
546 * `hide_followers`
547 * `hide_followers_count`
548 * `hide_follows_count`
549 * `hide_favorites`
550 * `allow_following_move`
551 * `background`
552 * `show_role`
553 * `skip_thread_containment`
554 * `fields`
555 * `discoverable`
556 * `actor_type`
557
558 * Responses:
559
560 Status: 200
561
562 ```json
563 {"status": "success"}
564 ```
565
566 Status: 400
567
568 ```json
569 {"errors":
570 {"actor_type": "is invalid"},
571 {"email": "has invalid format"},
572 ...
573 }
574 ```
575
576 Status: 404
577
578 ```json
579 {"error": "Not found"}
580 ```
581
582 ## `GET /api/pleroma/admin/reports`
583
584 ### Get a list of reports
585
586 - Params:
587 - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
588 - *optional* `limit`: **integer** the number of records to retrieve
589 - *optional* `page`: **integer** page number
590 - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
591 - Response:
592 - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
593 - On success: JSON, returns a list of reports, where:
594 - `account`: the user who has been reported
595 - `actor`: the user who has sent the report
596 - `statuses`: list of statuses that have been included to the report
597
598 ```json
599 {
600 "total" : 1,
601 "reports": [
602 {
603 "account": {
604 "acct": "user",
605 "avatar": "https://pleroma.example.org/images/avi.png",
606 "avatar_static": "https://pleroma.example.org/images/avi.png",
607 "bot": false,
608 "created_at": "2019-04-23T17:32:04.000Z",
609 "display_name": "User",
610 "emojis": [],
611 "fields": [],
612 "followers_count": 1,
613 "following_count": 1,
614 "header": "https://pleroma.example.org/images/banner.png",
615 "header_static": "https://pleroma.example.org/images/banner.png",
616 "id": "9i6dAJqSGSKMzLG2Lo",
617 "locked": false,
618 "note": "",
619 "pleroma": {
620 "confirmation_pending": false,
621 "hide_favorites": true,
622 "hide_followers": false,
623 "hide_follows": false,
624 "is_admin": false,
625 "is_moderator": false,
626 "relationship": {},
627 "tags": []
628 },
629 "source": {
630 "note": "",
631 "pleroma": {},
632 "sensitive": false
633 },
634 "tags": ["force_unlisted"],
635 "statuses_count": 3,
636 "url": "https://pleroma.example.org/users/user",
637 "username": "user"
638 },
639 "actor": {
640 "acct": "lain",
641 "avatar": "https://pleroma.example.org/images/avi.png",
642 "avatar_static": "https://pleroma.example.org/images/avi.png",
643 "bot": false,
644 "created_at": "2019-03-28T17:36:03.000Z",
645 "display_name": "Roger Braun",
646 "emojis": [],
647 "fields": [],
648 "followers_count": 1,
649 "following_count": 1,
650 "header": "https://pleroma.example.org/images/banner.png",
651 "header_static": "https://pleroma.example.org/images/banner.png",
652 "id": "9hEkA5JsvAdlSrocam",
653 "locked": false,
654 "note": "",
655 "pleroma": {
656 "confirmation_pending": false,
657 "hide_favorites": false,
658 "hide_followers": false,
659 "hide_follows": false,
660 "is_admin": false,
661 "is_moderator": false,
662 "relationship": {},
663 "tags": []
664 },
665 "source": {
666 "note": "",
667 "pleroma": {},
668 "sensitive": false
669 },
670 "tags": ["force_unlisted"],
671 "statuses_count": 1,
672 "url": "https://pleroma.example.org/users/lain",
673 "username": "lain"
674 },
675 "content": "Please delete it",
676 "created_at": "2019-04-29T19:48:15.000Z",
677 "id": "9iJGOv1j8hxuw19bcm",
678 "state": "open",
679 "statuses": [
680 {
681 "account": { ... },
682 "application": {
683 "name": "Web",
684 "website": null
685 },
686 "bookmarked": false,
687 "card": null,
688 "content": "<span class=\"h-card\"><a data-user=\"9hEkA5JsvAdlSrocam\" class=\"u-url mention\" href=\"https://pleroma.example.org/users/lain\">@<span>lain</span></a></span> click on my link <a href=\"https://www.google.com/\">https://www.google.com/</a>",
689 "created_at": "2019-04-23T19:15:47.000Z",
690 "emojis": [],
691 "favourited": false,
692 "favourites_count": 0,
693 "id": "9i6mQ9uVrrOmOime8m",
694 "in_reply_to_account_id": null,
695 "in_reply_to_id": null,
696 "language": null,
697 "media_attachments": [],
698 "mentions": [
699 {
700 "acct": "lain",
701 "id": "9hEkA5JsvAdlSrocam",
702 "url": "https://pleroma.example.org/users/lain",
703 "username": "lain"
704 },
705 {
706 "acct": "user",
707 "id": "9i6dAJqSGSKMzLG2Lo",
708 "url": "https://pleroma.example.org/users/user",
709 "username": "user"
710 }
711 ],
712 "muted": false,
713 "pinned": false,
714 "pleroma": {
715 "content": {
716 "text/plain": "@lain click on my link https://www.google.com/"
717 },
718 "conversation_id": 28,
719 "in_reply_to_account_acct": null,
720 "local": true,
721 "spoiler_text": {
722 "text/plain": ""
723 }
724 },
725 "reblog": null,
726 "reblogged": false,
727 "reblogs_count": 0,
728 "replies_count": 0,
729 "sensitive": false,
730 "spoiler_text": "",
731 "tags": [],
732 "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
733 "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
734 "visibility": "direct"
735 }
736 ]
737 }
738 ]
739 }
740 ```
741
742 ## `GET /api/pleroma/admin/grouped_reports`
743
744 ### Get a list of reports, grouped by status
745
746 - Params: none
747 - On success: JSON, returns a list of reports, where:
748 - `date`: date of the latest report
749 - `account`: the user who has been reported (see `/api/pleroma/admin/reports` for reference)
750 - `status`: reported status (see `/api/pleroma/admin/reports` for reference)
751 - `actors`: users who had reported this status (see `/api/pleroma/admin/reports` for reference)
752 - `reports`: reports (see `/api/pleroma/admin/reports` for reference)
753
754 ```json
755 "reports": [
756 {
757 "date": "2019-10-07T12:31:39.615149Z",
758 "account": { ... },
759 "status": { ... },
760 "actors": [{ ... }, { ... }],
761 "reports": [{ ... }]
762 }
763 ]
764 ```
765
766 ## `GET /api/pleroma/admin/reports/:id`
767
768 ### Get an individual report
769
770 - Params:
771 - `id`
772 - Response:
773 - On failure:
774 - 403 Forbidden `{"error": "error_msg"}`
775 - 404 Not Found `"Not found"`
776 - On success: JSON, Report object (see above)
777
778 ## `PATCH /api/pleroma/admin/reports`
779
780 ### Change the state of one or multiple reports
781
782 - Params:
783
784 ```json
785 `reports`: [
786 {
787 `id`, // required, report id
788 `state` // required, the new state. Valid values are `open`, `closed` and `resolved`
789 },
790 ...
791 ]
792 ```
793
794 - Response:
795 - On failure:
796 - 400 Bad Request, JSON:
797
798 ```json
799 [
800 {
801 `id`, // report id
802 `error` // error message
803 }
804 ]
805 ```
806
807 - On success: `204`, empty response
808
809 ## `POST /api/pleroma/admin/reports/:id/notes`
810
811 ### Create report note
812
813 - Params:
814 - `id`: required, report id
815 - `content`: required, the message
816 - Response:
817 - On failure:
818 - 400 Bad Request `"Invalid parameters"` when `status` is missing
819 - On success: `204`, empty response
820
821 ## `DELETE /api/pleroma/admin/reports/:report_id/notes/:id`
822
823 ### Delete report note
824
825 - Params:
826 - `report_id`: required, report id
827 - `id`: required, note id
828 - Response:
829 - On failure:
830 - 400 Bad Request `"Invalid parameters"` when `status` is missing
831 - On success: `204`, empty response
832
833 ## `GET /api/pleroma/admin/statuses/:id`
834
835 ### Show status by id
836
837 - Params:
838 - `id`: required, status id
839 - Response:
840 - On failure:
841 - 404 Not Found `"Not Found"`
842 - On success: JSON, Mastodon Status entity
843
844 ## `PUT /api/pleroma/admin/statuses/:id`
845
846 ### Change the scope of an individual reported status
847
848 - Params:
849 - `id`
850 - `sensitive`: optional, valid values are `true` or `false`
851 - `visibility`: optional, valid values are `public`, `private` and `unlisted`
852 - Response:
853 - On failure:
854 - 400 Bad Request `"Unsupported visibility"`
855 - 403 Forbidden `{"error": "error_msg"}`
856 - 404 Not Found `"Not found"`
857 - On success: JSON, Mastodon Status entity
858
859 ## `DELETE /api/pleroma/admin/statuses/:id`
860
861 ### Delete an individual reported status
862
863 - Params:
864 - `id`
865 - Response:
866 - On failure:
867 - 403 Forbidden `{"error": "error_msg"}`
868 - 404 Not Found `"Not found"`
869 - On success: 200 OK `{}`
870
871 ## `GET /api/pleroma/admin/restart`
872
873 ### Restarts pleroma application
874
875 **Only works when configuration from database is enabled.**
876
877 - Params: none
878 - Response:
879 - On failure:
880 - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
881
882 ```json
883 {}
884 ```
885
886 ## `GET /api/pleroma/admin/need_reboot`
887
888 ### Returns the flag whether the pleroma should be restarted
889
890 - Params: none
891 - Response:
892 - `need_reboot` - boolean
893 ```json
894 {
895 "need_reboot": false
896 }
897 ```
898
899 ## `GET /api/pleroma/admin/config`
900
901 ### Get list of merged default settings with saved in database.
902
903 *If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
904
905 **Only works when configuration from database is enabled.**
906
907 - Params:
908 - `only_db`: true (*optional*, get only saved in database settings)
909 - Response:
910 - On failure:
911 - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
912
913 ```json
914 {
915 "configs": [
916 {
917 "group": ":pleroma",
918 "key": "Pleroma.Upload",
919 "value": []
920 }
921 ],
922 "need_reboot": true
923 }
924 ```
925
926 ## `POST /api/pleroma/admin/config`
927
928 ### Update config settings
929
930 *If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
931
932 **Only works when configuration from database is enabled.**
933
934 Some modifications are necessary to save the config settings correctly:
935
936 - strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules;
937 ```
938 "Pleroma.Upload" -> Pleroma.Upload
939 "Oban" -> Oban
940 ```
941 - strings starting with `:` will be converted to atoms;
942 ```
943 ":pleroma" -> :pleroma
944 ```
945 - objects with `tuple` key and array value will be converted to tuples;
946 ```
947 {"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []}
948 ```
949 - arrays with *tuple objects* will be converted to keywords;
950 ```
951 [{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"]
952 ```
953
954 Most of the settings will be applied in `runtime`, this means that you don't need to restart the instance. But some settings are applied in `compile time` and require a reboot of the instance, such as:
955 - all settings inside these keys:
956 - `:hackney_pools`
957 - `:connections_pool`
958 - `:pools`
959 - `:chat`
960 - partially settings inside these keys:
961 - `:seconds_valid` in `Pleroma.Captcha`
962 - `:proxy_remote` in `Pleroma.Upload`
963 - `:upload_limit` in `:instance`
964
965 - Params:
966 - `configs` - array of config objects
967 - config object params:
968 - `group` - string (**required**)
969 - `key` - string (**required**)
970 - `value` - string, [], {} or {"tuple": []} (**required**)
971 - `delete` - true (*optional*, if setting must be deleted)
972 - `subkeys` - array of strings (*optional*, only works when `delete=true` parameter is passed, otherwise will be ignored)
973
974 *When a value have several nested settings, you can delete only some nested settings by passing a parameter `subkeys`, without deleting all settings by key.*
975 ```
976 [subkey: val1, subkey2: val2, subkey3: val3] \\ initial value
977 {"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion
978 [subkey2: val2] \\ value after deletion
979 ```
980
981 *Most of the settings can be partially updated through merge old values with new values, except settings value of which is list or is not keyword.*
982
983 Example of setting without keyword in value:
984 ```elixir
985 config :tesla, :adapter, Tesla.Adapter.Hackney
986 ```
987
988 List of settings which support only full update by key:
989 ```elixir
990 @full_key_update [
991 {:pleroma, :ecto_repos},
992 {:quack, :meta},
993 {:mime, :types},
994 {:cors_plug, [:max_age, :methods, :expose, :headers]},
995 {:auto_linker, :opts},
996 {:swarm, :node_blacklist},
997 {:logger, :backends}
998 ]
999 ```
1000
1001 List of settings which support only full update by subkey:
1002 ```elixir
1003 @full_subkey_update [
1004 {:pleroma, :assets, :mascots},
1005 {:pleroma, :emoji, :groups},
1006 {:pleroma, :workers, :retries},
1007 {:pleroma, :mrf_subchain, :match_actor},
1008 {:pleroma, :mrf_keyword, :replace}
1009 ]
1010 ```
1011
1012 *Settings without explicit key must be sended in separate config object params.*
1013 ```elixir
1014 config :quack,
1015 level: :debug,
1016 meta: [:all],
1017 ...
1018 ```
1019 ```json
1020 {
1021 "configs": [
1022 {"group": ":quack", "key": ":level", "value": ":debug"},
1023 {"group": ":quack", "key": ":meta", "value": [":all"]},
1024 ...
1025 ]
1026 }
1027 ```
1028 - Request:
1029
1030 ```json
1031 {
1032 "configs": [
1033 {
1034 "group": ":pleroma",
1035 "key": "Pleroma.Upload",
1036 "value": [
1037 {"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
1038 {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]},
1039 {"tuple": [":link_name", true]},
1040 {"tuple": [":proxy_remote", false]},
1041 {"tuple": [":proxy_opts", [
1042 {"tuple": [":redirect_on_failure", false]},
1043 {"tuple": [":max_body_length", 1048576]},
1044 {"tuple": [":http", [
1045 {"tuple": [":follow_redirect", true]},
1046 {"tuple": [":pool", ":upload"]},
1047 ]]}
1048 ]
1049 ]},
1050 {"tuple": [":dispatch", {
1051 "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []]
1052 }]}
1053 ]
1054 }
1055 ]
1056 }
1057 ```
1058
1059 - Response:
1060 - On failure:
1061 - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
1062 ```json
1063 {
1064 "configs": [
1065 {
1066 "group": ":pleroma",
1067 "key": "Pleroma.Upload",
1068 "value": [...]
1069 }
1070 ],
1071 "need_reboot": true
1072 }
1073 ```
1074
1075 ## ` GET /api/pleroma/admin/config/descriptions`
1076
1077 ### Get JSON with config descriptions.
1078 Loads json generated from `config/descriptions.exs`.
1079
1080 - Params: none
1081 - Response:
1082
1083 ```json
1084 [{
1085 "group": ":pleroma", // string
1086 "key": "ModuleName", // string
1087 "type": "group", // string or list with possible values,
1088 "description": "Upload general settings", // string
1089 "children": [
1090 {
1091 "key": ":uploader", // string or module name `Pleroma.Upload`
1092 "type": "module",
1093 "description": "Module which will be used for uploads",
1094 "suggestions": ["module1", "module2"]
1095 },
1096 {
1097 "key": ":filters",
1098 "type": ["list", "module"],
1099 "description": "List of filter modules for uploads",
1100 "suggestions": [
1101 "module1", "module2", "module3"
1102 ]
1103 }
1104 ]
1105 }]
1106 ```
1107
1108 ## `GET /api/pleroma/admin/moderation_log`
1109
1110 ### Get moderation log
1111
1112 - Params:
1113 - *optional* `page`: **integer** page number
1114 - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
1115 - *optional* `start_date`: **datetime (ISO 8601)** filter logs by creation date, start from `start_date`. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. `2005-08-09T18:31:42`
1116 - *optional* `end_date`: **datetime (ISO 8601)** filter logs by creation date, end by from `end_date`. Accepts datetime in ISO 8601 format (YYYY-MM-DDThh:mm:ss), e.g. 2005-08-09T18:31:42
1117 - *optional* `user_id`: **integer** filter logs by actor's id
1118 - *optional* `search`: **string** search logs by the log message
1119 - Response:
1120
1121 ```json
1122 [
1123 {
1124 "data": {
1125 "actor": {
1126 "id": 1,
1127 "nickname": "lain"
1128 },
1129 "action": "relay_follow"
1130 },
1131 "time": 1502812026, // timestamp
1132 "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
1133 }
1134 ]
1135 ```
1136
1137 ## `POST /api/pleroma/admin/reload_emoji`
1138
1139 ### Reload the instance's custom emoji
1140
1141 - Authentication: required
1142 - Params: None
1143 - Response: JSON, "ok" and 200 status
1144
1145 ## `PATCH /api/pleroma/admin/users/confirm_email`
1146
1147 ### Confirm users' emails
1148
1149 - Params:
1150 - `nicknames`
1151 - Response: Array of user nicknames
1152
1153 ## `PATCH /api/pleroma/admin/users/resend_confirmation_email`
1154
1155 ### Resend confirmation email
1156
1157 - Params:
1158 - `nicknames`
1159 - Response: Array of user nicknames
1160
1161 ## `GET /api/pleroma/admin/stats`
1162
1163 ### Stats
1164
1165 - Query Params:
1166 - *optional* `instance`: **string** instance hostname (without protocol) to get stats for
1167 - Example: `https://mypleroma.org/api/pleroma/admin/stats?instance=lain.com`
1168
1169 - Response:
1170
1171 ```json
1172 {
1173 "status_visibility": {
1174 "direct": 739,
1175 "private": 9,
1176 "public": 17,
1177 "unlisted": 14
1178 }
1179 }
1180 ```
1181
1182 ## `GET /api/pleroma/admin/oauth_app`
1183
1184 ### List OAuth app
1185
1186 - Params:
1187 - *optional* `name`
1188 - *optional* `client_id`
1189 - *optional* `page`
1190 - *optional* `page_size`
1191 - *optional* `trusted`
1192
1193 - Response:
1194
1195 ```json
1196 {
1197 "apps": [
1198 {
1199 "id": 1,
1200 "name": "App name",
1201 "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
1202 "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
1203 "redirect_uri": "https://example.com/oauth-callback",
1204 "website": "https://example.com",
1205 "trusted": true
1206 }
1207 ],
1208 "count": 17,
1209 "page_size": 50
1210 }
1211 ```
1212
1213
1214 ## `POST /api/pleroma/admin/oauth_app`
1215
1216 ### Create OAuth App
1217
1218 - Params:
1219 - `name`
1220 - `redirect_uris`
1221 - `scopes`
1222 - *optional* `website`
1223 - *optional* `trusted`
1224
1225 - Response:
1226
1227 ```json
1228 {
1229 "id": 1,
1230 "name": "App name",
1231 "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
1232 "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
1233 "redirect_uri": "https://example.com/oauth-callback",
1234 "website": "https://example.com",
1235 "trusted": true
1236 }
1237 ```
1238
1239 - On failure:
1240 ```json
1241 {
1242 "redirect_uris": "can't be blank",
1243 "name": "can't be blank"
1244 }
1245 ```
1246
1247 ## `PATCH /api/pleroma/admin/oauth_app/:id`
1248
1249 ### Update OAuth App
1250
1251 - Params:
1252 - *optional* `name`
1253 - *optional* `redirect_uris`
1254 - *optional* `scopes`
1255 - *optional* `website`
1256 - *optional* `trusted`
1257
1258 - Response:
1259
1260 ```json
1261 {
1262 "id": 1,
1263 "name": "App name",
1264 "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
1265 "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
1266 "redirect_uri": "https://example.com/oauth-callback",
1267 "website": "https://example.com",
1268 "trusted": true
1269 }
1270 ```
1271
1272 ## `DELETE /api/pleroma/admin/oauth_app/:id`
1273
1274 ### Delete OAuth App
1275
1276 - Params: None
1277
1278 - Response:
1279 - On success: `204`, empty response
1280 - On failure:
1281 - 400 Bad Request `"Invalid parameters"` when `status` is missing
1282
1283 ## `GET /api/pleroma/admin/media_proxy_caches`
1284
1285 ### Get a list of all banned MediaProxy URLs in Cachex
1286
1287 - Authentication: required
1288 - Params:
1289 - *optional* `page`: **integer** page number
1290 - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
1291 - *optional* `query`: **string** search term
1292
1293 - Response:
1294
1295 ``` json
1296 {
1297 "page_size": integer,
1298 "count": integer,
1299 "urls": [
1300 "http://example.com/media/a688346.jpg",
1301 "http://example.com/media/fb1f4d.jpg"
1302 ]
1303 }
1304
1305 ```
1306
1307 ## `POST /api/pleroma/admin/media_proxy_caches/delete`
1308
1309 ### Remove a banned MediaProxy URL from Cachex
1310
1311 - Authentication: required
1312 - Params:
1313 - `urls` (array)
1314
1315 - Response:
1316
1317 ``` json
1318 { }
1319
1320 ```
1321
1322 ## `POST /api/pleroma/admin/media_proxy_caches/purge`
1323
1324 ### Purge a MediaProxy URL
1325
1326 - Authentication: required
1327 - Params:
1328 - `urls` (array)
1329 - `ban` (boolean)
1330
1331 - Response:
1332
1333 ``` json
1334 { }
1335
1336 ```
1337
1338 ## GET /api/pleroma/admin/users/:nickname/chats
1339
1340 ### List a user's chats
1341
1342 - Params: None
1343
1344 - Response:
1345
1346 ```json
1347 [
1348 {
1349 "account": {
1350 "id": "someflakeid",
1351 "username": "somenick",
1352 ...
1353 },
1354 "id" : "1",
1355 "unread" : 2,
1356 "last_message" : {...}, // The last message in that chat
1357 "updated_at": "2020-04-21T15:11:46.000Z"
1358 }
1359 ]
1360 ```
1361
1362 ## GET /api/pleroma/admin/chats/:chat_id
1363
1364 ### View a single chat
1365
1366 - Params: None
1367
1368 - Response:
1369
1370 ```json
1371 {
1372 "account": {
1373 "id": "someflakeid",
1374 "username": "somenick",
1375 ...
1376 },
1377 "id" : "1",
1378 "unread" : 2,
1379 "last_message" : {...}, // The last message in that chat
1380 "updated_at": "2020-04-21T15:11:46.000Z"
1381 }
1382 ```
1383
1384 ## GET /api/pleroma/admin/chats/:chat_id/messages
1385
1386 ### List the messages in a chat
1387
1388 - Params: None
1389
1390 - Response:
1391
1392 ```json
1393 [
1394 {
1395 "account_id": "someflakeid",
1396 "chat_id": "1",
1397 "content": "Check this out :firefox:",
1398 "created_at": "2020-04-21T15:11:46.000Z",
1399 "emojis": [
1400 {
1401 "shortcode": "firefox",
1402 "static_url": "https://dontbulling.me/emoji/Firefox.gif",
1403 "url": "https://dontbulling.me/emoji/Firefox.gif",
1404 "visible_in_picker": false
1405 }
1406 ],
1407 "id": "13",
1408 "unread": true
1409 },
1410 {
1411 "account_id": "someflakeid",
1412 "chat_id": "1",
1413 "content": "Whats' up?",
1414 "created_at": "2020-04-21T15:06:45.000Z",
1415 "emojis": [],
1416 "id": "12",
1417 "unread": false
1418 }
1419 ]
1420 ```
1421
1422 ## DELETE /api/pleroma/admin/chats/:chat_id/messages/:message_id
1423
1424 ### Delete a single message
1425
1426 - Params: None
1427
1428 - Response:
1429
1430 ```json
1431 {
1432 "account_id": "someflakeid",
1433 "chat_id": "1",
1434 "content": "Check this out :firefox:",
1435 "created_at": "2020-04-21T15:11:46.000Z",
1436 "emojis": [
1437 {
1438 "shortcode": "firefox",
1439 "static_url": "https://dontbulling.me/emoji/Firefox.gif",
1440 "url": "https://dontbulling.me/emoji/Firefox.gif",
1441 "visible_in_picker": false
1442 }
1443 ],
1444 "id": "13",
1445 "unread": false
1446 }
1447 ```