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