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