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