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