55f8749e18cfeabe00b5df00fc74a3d9defe70e0
[akkoma] / docs / API / admin_api.md
1 # Admin API
2
3 Authentication is required and the user must be an admin.
4
5 ## `/api/pleroma/admin/users`
6
7 ### List users
8
9 - Method `GET`
10 - Query Params:
11 - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
12 - *optional* `filters`: **string** comma-separated string of filters:
13 - `local`: only local users
14 - `external`: only external users
15 - `active`: only active users
16 - `deactivated`: only deactivated users
17 - `is_admin`: users with admin role
18 - `is_moderator`: users with moderator role
19 - *optional* `page`: **integer** page number
20 - *optional* `page_size`: **integer** number of users per page (default is `50`)
21 - *optional* `tags`: **[string]** tags list
22 - *optional* `name`: **string** user display name
23 - *optional* `email`: **string** user email
24 - 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`
25 - Response:
26
27 ```json
28 {
29 "page_size": integer,
30 "count": integer,
31 "users": [
32 {
33 "deactivated": bool,
34 "id": integer,
35 "nickname": string,
36 "roles": {
37 "admin": bool,
38 "moderator": bool
39 },
40 "local": bool,
41 "tags": array,
42 "avatar": string,
43 "display_name": string
44 },
45 ...
46 ]
47 }
48 ```
49
50 ## `/api/pleroma/admin/users`
51
52 ### Remove a user
53
54 - Method `DELETE`
55 - Params:
56 - `nickname`
57 - Response: User’s nickname
58
59 ### Create a user
60
61 - Method: `POST`
62 - Params:
63 `users`: [
64 {
65 `nickname`,
66 `email`,
67 `password`
68 }
69 ]
70 - Response: User’s nickname
71
72 ## `/api/pleroma/admin/users/follow`
73 ### Make a user follow another user
74
75 - Methods: `POST`
76 - Params:
77 - `follower`: The nickname of the follower
78 - `followed`: The nickname of the followed
79 - Response:
80 - "ok"
81
82 ## `/api/pleroma/admin/users/unfollow`
83 ### Make a user unfollow another user
84
85 - Methods: `POST`
86 - Params:
87 - `follower`: The nickname of the follower
88 - `followed`: The nickname of the followed
89 - Response:
90 - "ok"
91
92 ## `/api/pleroma/admin/users/:nickname/toggle_activation`
93
94 ### Toggle user activation
95
96 - Method: `PATCH`
97 - Params:
98 - `nickname`
99 - Response: User’s object
100
101 ```json
102 {
103 "deactivated": bool,
104 "id": integer,
105 "nickname": string
106 }
107 ```
108
109 ## `/api/pleroma/admin/users/tag`
110
111 ### Tag a list of users
112
113 - Method: `PUT`
114 - Params:
115 - `nicknames` (array)
116 - `tags` (array)
117
118 ### Untag a list of users
119
120 - Method: `DELETE`
121 - Params:
122 - `nicknames` (array)
123 - `tags` (array)
124
125 ## `/api/pleroma/admin/users/:nickname/permission_group`
126
127 ### Get user user permission groups membership
128
129 - Method: `GET`
130 - Params: none
131 - Response:
132
133 ```json
134 {
135 "is_moderator": bool,
136 "is_admin": bool
137 }
138 ```
139
140 ## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group`
141
142 Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
143
144 ### Get user user permission groups membership per permission group
145
146 - Method: `GET`
147 - Params: none
148 - Response:
149
150 ```json
151 {
152 "is_moderator": bool,
153 "is_admin": bool
154 }
155 ```
156
157 ## `POST /api/pleroma/admin/users/permission_group/:permission_group`
158
159 ### Add user in permission group
160
161 - Params:
162 - `nicknames`: nicknames array
163 - Response:
164 - On failure: `{"error": "…"}`
165 - On success: JSON of the `user.info`
166
167 ## `DELETE /api/pleroma/admin/users/permission_group/:permission_group`
168
169 ### Remove user from permission group
170
171 - Params:
172 - `nicknames`: nicknames array
173 - Response:
174 - On failure: `{"error": "…"}`
175 - On success: JSON of the `user.info`
176 - Note: An admin cannot revoke their own admin status.
177
178 ## `PATCH /api/pleroma/admin/users/activate`
179
180 ### Activate user
181
182 - Params:
183 - `nicknames`: nicknames array
184 - Response:
185
186 ```json
187 {
188 users: [
189 {
190 // user object
191 }
192 ]
193 }
194 ```
195
196 ## `PATCH /api/pleroma/admin/users/deactivate`
197
198 ### Deactivate user
199
200 - Params:
201 - `nicknames`: nicknames array
202 - Response:
203
204 ```json
205 {
206 users: [
207 {
208 // user object
209 }
210 ]
211 }
212 ```
213
214 ## `/api/pleroma/admin/users/:nickname_or_id`
215
216 ### Retrive the details of a user
217
218 - Method: `GET`
219 - Params:
220 - `nickname` or `id`
221 - Response:
222 - On failure: `Not found`
223 - On success: JSON of the user
224
225 ## `/api/pleroma/admin/users/:nickname_or_id/statuses`
226
227 ### Retrive user's latest statuses
228
229 - Method: `GET`
230 - Params:
231 - `nickname` or `id`
232 - *optional* `page_size`: number of statuses to return (default is `20`)
233 - *optional* `godmode`: `true`/`false` – allows to see private statuses
234 - Response:
235 - On failure: `Not found`
236 - On success: JSON array of user's latest statuses
237
238 ## `/api/pleroma/admin/relay`
239
240 ### Follow a Relay
241
242 - Methods: `POST`
243 - Params:
244 - `relay_url`
245 - Response:
246 - On success: URL of the followed relay
247
248 ### Unfollow a Relay
249
250 - Methods: `DELETE`
251 - Params:
252 - `relay_url`
253 - Response:
254 - On success: URL of the unfollowed relay
255
256 ## `/api/pleroma/admin/users/invite_token`
257
258 ### Create an account registration invite token
259
260 - Methods: `POST`
261 - Params:
262 - *optional* `max_use` (integer)
263 - *optional* `expires_at` (date string e.g. "2019-04-07")
264 - Response:
265
266 ```json
267 {
268 "id": integer,
269 "token": string,
270 "used": boolean,
271 "expires_at": date,
272 "uses": integer,
273 "max_use": integer,
274 "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
275 }
276 ```
277
278 ## `/api/pleroma/admin/users/invites`
279
280 ### Get a list of generated invites
281
282 - Methods: `GET`
283 - Params: none
284 - Response:
285
286 ```json
287 {
288
289 "invites": [
290 {
291 "id": integer,
292 "token": string,
293 "used": boolean,
294 "expires_at": date,
295 "uses": integer,
296 "max_use": integer,
297 "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
298 },
299 ...
300 ]
301 }
302 ```
303
304 ## `/api/pleroma/admin/users/revoke_invite`
305
306 ### Revoke invite by token
307
308 - Methods: `POST`
309 - Params:
310 - `token`
311 - Response:
312
313 ```json
314 {
315 "id": integer,
316 "token": string,
317 "used": boolean,
318 "expires_at": date,
319 "uses": integer,
320 "max_use": integer,
321 "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
322
323 }
324 ```
325
326
327 ## `/api/pleroma/admin/users/email_invite`
328
329 ### Sends registration invite via email
330
331 - Methods: `POST`
332 - Params:
333 - `email`
334 - `name`, optional
335
336 ## `/api/pleroma/admin/users/:nickname/password_reset`
337
338 ### Get a password reset token for a given nickname
339
340 - Methods: `GET`
341 - Params: none
342 - Response:
343
344 ```json
345 {
346 "token": "base64 reset token",
347 "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token"
348 }
349 ```
350
351
352 ## `/api/pleroma/admin/users/:nickname/force_password_reset`
353
354 ### Force passord reset for a user with a given nickname
355
356 - Methods: `PATCH`
357 - Params: none
358 - Response: none (code `204`)
359
360 ## `/api/pleroma/admin/reports`
361 ### Get a list of reports
362 - Method `GET`
363 - Params:
364 - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
365 - *optional* `limit`: **integer** the number of records to retrieve
366 - *optional* `page`: **integer** page number
367 - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
368 - Response:
369 - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
370 - On success: JSON, returns a list of reports, where:
371 - `account`: the user who has been reported
372 - `actor`: the user who has sent the report
373 - `statuses`: list of statuses that have been included to the report
374
375 ```json
376 {
377 "total" : 1,
378 "reports": [
379 {
380 "account": {
381 "acct": "user",
382 "avatar": "https://pleroma.example.org/images/avi.png",
383 "avatar_static": "https://pleroma.example.org/images/avi.png",
384 "bot": false,
385 "created_at": "2019-04-23T17:32:04.000Z",
386 "display_name": "User",
387 "emojis": [],
388 "fields": [],
389 "followers_count": 1,
390 "following_count": 1,
391 "header": "https://pleroma.example.org/images/banner.png",
392 "header_static": "https://pleroma.example.org/images/banner.png",
393 "id": "9i6dAJqSGSKMzLG2Lo",
394 "locked": false,
395 "note": "",
396 "pleroma": {
397 "confirmation_pending": false,
398 "hide_favorites": true,
399 "hide_followers": false,
400 "hide_follows": false,
401 "is_admin": false,
402 "is_moderator": false,
403 "relationship": {},
404 "tags": []
405 },
406 "source": {
407 "note": "",
408 "pleroma": {},
409 "sensitive": false
410 },
411 "tags": ["force_unlisted"],
412 "statuses_count": 3,
413 "url": "https://pleroma.example.org/users/user",
414 "username": "user"
415 },
416 "actor": {
417 "acct": "lain",
418 "avatar": "https://pleroma.example.org/images/avi.png",
419 "avatar_static": "https://pleroma.example.org/images/avi.png",
420 "bot": false,
421 "created_at": "2019-03-28T17:36:03.000Z",
422 "display_name": "Roger Braun",
423 "emojis": [],
424 "fields": [],
425 "followers_count": 1,
426 "following_count": 1,
427 "header": "https://pleroma.example.org/images/banner.png",
428 "header_static": "https://pleroma.example.org/images/banner.png",
429 "id": "9hEkA5JsvAdlSrocam",
430 "locked": false,
431 "note": "",
432 "pleroma": {
433 "confirmation_pending": false,
434 "hide_favorites": false,
435 "hide_followers": false,
436 "hide_follows": false,
437 "is_admin": false,
438 "is_moderator": false,
439 "relationship": {},
440 "tags": []
441 },
442 "source": {
443 "note": "",
444 "pleroma": {},
445 "sensitive": false
446 },
447 "tags": ["force_unlisted"],
448 "statuses_count": 1,
449 "url": "https://pleroma.example.org/users/lain",
450 "username": "lain"
451 },
452 "content": "Please delete it",
453 "created_at": "2019-04-29T19:48:15.000Z",
454 "id": "9iJGOv1j8hxuw19bcm",
455 "state": "open",
456 "statuses": [
457 {
458 "account": { ... },
459 "application": {
460 "name": "Web",
461 "website": null
462 },
463 "bookmarked": false,
464 "card": null,
465 "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>",
466 "created_at": "2019-04-23T19:15:47.000Z",
467 "emojis": [],
468 "favourited": false,
469 "favourites_count": 0,
470 "id": "9i6mQ9uVrrOmOime8m",
471 "in_reply_to_account_id": null,
472 "in_reply_to_id": null,
473 "language": null,
474 "media_attachments": [],
475 "mentions": [
476 {
477 "acct": "lain",
478 "id": "9hEkA5JsvAdlSrocam",
479 "url": "https://pleroma.example.org/users/lain",
480 "username": "lain"
481 },
482 {
483 "acct": "user",
484 "id": "9i6dAJqSGSKMzLG2Lo",
485 "url": "https://pleroma.example.org/users/user",
486 "username": "user"
487 }
488 ],
489 "muted": false,
490 "pinned": false,
491 "pleroma": {
492 "content": {
493 "text/plain": "@lain click on my link https://www.google.com/"
494 },
495 "conversation_id": 28,
496 "in_reply_to_account_acct": null,
497 "local": true,
498 "spoiler_text": {
499 "text/plain": ""
500 }
501 },
502 "reblog": null,
503 "reblogged": false,
504 "reblogs_count": 0,
505 "replies_count": 0,
506 "sensitive": false,
507 "spoiler_text": "",
508 "tags": [],
509 "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
510 "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
511 "visibility": "direct"
512 }
513 ]
514 }
515 ]
516 }
517 ```
518
519 ## `/api/pleroma/admin/reports/:id`
520 ### Get an individual report
521 - Method `GET`
522 - Params:
523 - `id`
524 - Response:
525 - On failure:
526 - 403 Forbidden `{"error": "error_msg"}`
527 - 404 Not Found `"Not found"`
528 - On success: JSON, Report object (see above)
529
530 ## `/api/pleroma/admin/reports/:id`
531 ### Change the state of the report
532 - Method `PUT`
533 - Params:
534 - `id`
535 - `state`: required, the new state. Valid values are `open`, `closed` and `resolved`
536 - Response:
537 - On failure:
538 - 400 Bad Request `"Unsupported state"`
539 - 403 Forbidden `{"error": "error_msg"}`
540 - 404 Not Found `"Not found"`
541 - On success: JSON, Report object (see above)
542
543 ## `/api/pleroma/admin/reports/:id/respond`
544 ### Respond to a report
545 - Method `POST`
546 - Params:
547 - `id`
548 - `status`: required, the message
549 - Response:
550 - On failure:
551 - 400 Bad Request `"Invalid parameters"` when `status` is missing
552 - 403 Forbidden `{"error": "error_msg"}`
553 - 404 Not Found `"Not found"`
554 - On success: JSON, created Mastodon Status entity
555
556 ```json
557 {
558 "account": { ... },
559 "application": {
560 "name": "Web",
561 "website": null
562 },
563 "bookmarked": false,
564 "card": null,
565 "content": "Your claim is going to be closed",
566 "created_at": "2019-05-11T17:13:03.000Z",
567 "emojis": [],
568 "favourited": false,
569 "favourites_count": 0,
570 "id": "9ihuiSL1405I65TmEq",
571 "in_reply_to_account_id": null,
572 "in_reply_to_id": null,
573 "language": null,
574 "media_attachments": [],
575 "mentions": [
576 {
577 "acct": "user",
578 "id": "9i6dAJqSGSKMzLG2Lo",
579 "url": "https://pleroma.example.org/users/user",
580 "username": "user"
581 },
582 {
583 "acct": "admin",
584 "id": "9hEkA5JsvAdlSrocam",
585 "url": "https://pleroma.example.org/users/admin",
586 "username": "admin"
587 }
588 ],
589 "muted": false,
590 "pinned": false,
591 "pleroma": {
592 "content": {
593 "text/plain": "Your claim is going to be closed"
594 },
595 "conversation_id": 35,
596 "in_reply_to_account_acct": null,
597 "local": true,
598 "spoiler_text": {
599 "text/plain": ""
600 }
601 },
602 "reblog": null,
603 "reblogged": false,
604 "reblogs_count": 0,
605 "replies_count": 0,
606 "sensitive": false,
607 "spoiler_text": "",
608 "tags": [],
609 "uri": "https://pleroma.example.org/objects/cab0836d-9814-46cd-a0ea-529da9db5fcb",
610 "url": "https://pleroma.example.org/notice/9ihuiSL1405I65TmEq",
611 "visibility": "direct"
612 }
613 ```
614
615 ## `/api/pleroma/admin/statuses/:id`
616 ### Change the scope of an individual reported status
617 - Method `PUT`
618 - Params:
619 - `id`
620 - `sensitive`: optional, valid values are `true` or `false`
621 - `visibility`: optional, valid values are `public`, `private` and `unlisted`
622 - Response:
623 - On failure:
624 - 400 Bad Request `"Unsupported visibility"`
625 - 403 Forbidden `{"error": "error_msg"}`
626 - 404 Not Found `"Not found"`
627 - On success: JSON, Mastodon Status entity
628
629 ## `/api/pleroma/admin/statuses/:id`
630 ### Delete an individual reported status
631 - Method `DELETE`
632 - Params:
633 - `id`
634 - Response:
635 - On failure:
636 - 403 Forbidden `{"error": "error_msg"}`
637 - 404 Not Found `"Not found"`
638 - On success: 200 OK `{}`
639
640
641 ## `/api/pleroma/admin/config/migrate_to_db`
642 ### Run mix task pleroma.config migrate_to_db
643 Copy settings on key `:pleroma` to DB.
644 - Method `GET`
645 - Params: none
646 - Response:
647
648 ```json
649 {}
650 ```
651
652 ## `/api/pleroma/admin/config/migrate_from_db`
653 ### Run mix task pleroma.config migrate_from_db
654 Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB.
655 - Method `GET`
656 - Params: none
657 - Response:
658
659 ```json
660 {}
661 ```
662
663 ## `/api/pleroma/admin/config`
664 ### List config settings
665 List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
666 - Method `GET`
667 - Params: none
668 - Response:
669
670 ```json
671 {
672 configs: [
673 {
674 "group": string,
675 "key": string or string with leading `:` for atoms,
676 "value": string or {} or [] or {"tuple": []}
677 }
678 ]
679 }
680 ```
681
682 ## `/api/pleroma/admin/config`
683 ### Update config settings
684 Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
685 Module name can be passed as string, which starts with `Pleroma`, e.g. `"Pleroma.Upload"`.
686 Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`.
687 Tuples can be passed as `{"tuple": ["first_val", Pleroma.Module, []]}`.
688 `{"tuple": ["some_string", "Pleroma.Some.Module", []]}` will be converted to `{"some_string", Pleroma.Some.Module, []}`.
689 Keywords can be passed as lists with 2 child tuples, e.g.
690 `[{"tuple": ["first_val", Pleroma.Module]}, {"tuple": ["second_val", true]}]`.
691
692 If value contains list of settings `[subkey: val1, subkey2: val2, subkey3: val3]`, it's possible to remove only subkeys instead of all settings passing `subkeys` parameter. E.g.:
693 {"group": "pleroma", "key": "some_key", "delete": "true", "subkeys": [":subkey", ":subkey3"]}.
694
695 Compile time settings (need instance reboot):
696 - all settings by this keys:
697 - `:hackney_pools`
698 - `:chat`
699 - `Pleroma.Web.Endpoint`
700 - `Pleroma.Repo`
701 - part settings:
702 - `Pleroma.Captcha` -> `:seconds_valid`
703 - `Pleroma.Upload` -> `:proxy_remote`
704 - `:instance` -> `:upload_limit`
705
706 - Method `POST`
707 - Params:
708 - `configs` => [
709 - `group` (string)
710 - `key` (string or string with leading `:` for atoms)
711 - `value` (string, [], {} or {"tuple": []})
712 - `delete` = true (optional, if parameter must be deleted)
713 - `subkeys` [(string with leading `:` for atoms)] (optional, works only if `delete=true` parameter is passed, otherwise will be ignored)
714 ]
715
716 - Request (example):
717
718 ```json
719 {
720 configs: [
721 {
722 "group": "pleroma",
723 "key": "Pleroma.Upload",
724 "value": [
725 {"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
726 {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]},
727 {"tuple": [":link_name", true]},
728 {"tuple": [":proxy_remote", false]},
729 {"tuple": [":proxy_opts", [
730 {"tuple": [":redirect_on_failure", false]},
731 {"tuple": [":max_body_length", 1048576]},
732 {"tuple": [":http": [
733 {"tuple": [":follow_redirect", true]},
734 {"tuple": [":pool", ":upload"]},
735 ]]}
736 ]
737 ]},
738 {"tuple": [":dispatch", {
739 "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []]
740 }]}
741 ]
742 }
743 ]
744 }
745 ```
746
747 - Response:
748
749 ```json
750 {
751 configs: [
752 {
753 "group": string,
754 "key": string or string with leading `:` for atoms,
755 "value": string or {} or [] or {"tuple": []}
756 }
757 ]
758 }
759 ```
760
761 ## `/api/pleroma/admin/moderation_log`
762 ### Get moderation log
763 - Method `GET`
764 - Params:
765 - *optional* `page`: **integer** page number
766 - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
767 - *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`
768 - *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
769 - *optional* `user_id`: **integer** filter logs by actor's id
770 - *optional* `search`: **string** search logs by the log message
771 - Response:
772
773 ```json
774 [
775 {
776 "data": {
777 "actor": {
778 "id": 1,
779 "nickname": "lain"
780 },
781 "action": "relay_follow"
782 },
783 "time": 1502812026, // timestamp
784 "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
785 }
786 ]
787 ```
788
789 ## `POST /api/pleroma/admin/reload_emoji`
790 ### Reload the instance's custom emoji
791 * Method `POST`
792 * Authentication: required
793 * Params: None
794 * Response: JSON, "ok" and 200 status