admin_api.md 30.2 KB
Newer Older
Haelwenn's avatar
Haelwenn committed
1
# Admin API
Maxim Filippov's avatar
Maxim Filippov committed
2

Haelwenn's avatar
Haelwenn committed
3
4
Authentication is required and the user must be an admin.

5
Configuration options:
6

7
8
9
10
11
* `[:auth, :enforce_oauth_admin_scope_usage]` — OAuth admin scope requirement toggle.
    If `true`, admin actions explicitly demand admin OAuth scope(s) presence in OAuth token (client app must support admin scopes).
    If `false` and token doesn't have admin scope(s), `is_admin` user flag grants access to admin-specific actions.
    Note that client app needs to explicitly support admin scopes and request them when obtaining auth token.

12
## `GET /api/pleroma/admin/users`
Maxim Filippov's avatar
Maxim Filippov committed
13
14
15

### List users

Maxim Filippov's avatar
Maxim Filippov committed
16
- Query Params:
Alexander Strizhakov's avatar
Alexander Strizhakov committed
17
  - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
18
19
20
21
  - *optional* `filters`: **string** comma-separated string of filters:
    - `local`: only local users
    - `external`: only external users
    - `active`: only active users
22
    - `need_approval`: only unapproved users
23
    - `deactivated`: only deactivated users
Alexander Strizhakov's avatar
Alexander Strizhakov committed
24
25
    - `is_admin`: users with admin role
    - `is_moderator`: users with moderator role
26
27
  - *optional* `page`: **integer** page number
  - *optional* `page_size`: **integer** number of users per page (default is `50`)
Alexander Strizhakov's avatar
Alexander Strizhakov committed
28
29
30
31
  - *optional* `tags`: **[string]** tags list
  - *optional* `name`: **string** user display name
  - *optional* `email`: **string** user email
- 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`
Maxim Filippov's avatar
Maxim Filippov committed
32
33
- Response:

Sergey Suprunenko's avatar
Sergey Suprunenko committed
34
```json
Maxim Filippov's avatar
Maxim Filippov committed
35
36
37
38
{
  "page_size": integer,
  "count": integer,
  "users": [
Maxim Filippov's avatar
Maxim Filippov committed
39
    {
Maxim Filippov's avatar
Maxim Filippov committed
40
41
      "deactivated": bool,
      "id": integer,
42
43
44
45
46
47
      "nickname": string,
      "roles": {
        "admin": bool,
        "moderator": bool
      },
      "local": bool,
48
49
      "tags": array,
      "avatar": string,
50
      "display_name": string,
51
52
      "confirmation_pending": bool,
      "approval_pending": bool,
53
      "registration_reason": string,
Maxim Filippov's avatar
Maxim Filippov committed
54
55
    },
    ...
Maxim Filippov's avatar
Maxim Filippov committed
56
57
  ]
}
Maxim Filippov's avatar
Maxim Filippov committed
58
59
```

60
## DEPRECATED `DELETE /api/pleroma/admin/users`
Maxim Filippov's avatar
Maxim Filippov committed
61

Haelwenn's avatar
Haelwenn committed
62
### Remove a user
Maxim Filippov's avatar
Maxim Filippov committed
63
64
65
66
67

- Params:
  - `nickname`
- Response: User’s nickname

68
69
70
71
72
73
74
75
## `DELETE /api/pleroma/admin/users`

### Remove a user

- Params:
  - `nicknames`
- Response: Array of user nicknames

Haelwenn's avatar
Haelwenn committed
76
### Create a user
Maxim Filippov's avatar
Maxim Filippov committed
77
78
79

- Method: `POST`
- Params:
80
81
82
83
84
85
86
  `users`: [
    {
      `nickname`,
      `email`,
      `password`
    }
  ]
Maxim Filippov's avatar
Maxim Filippov committed
87
88
- Response: User’s nickname

89
90
## `POST /api/pleroma/admin/users/follow`

91
92
93
### Make a user follow another user

- Params:
94
95
  - `follower`: The nickname of the follower
  - `followed`: The nickname of the followed
96
- Response:
97
98
99
  - "ok"

## `POST /api/pleroma/admin/users/unfollow`
100
101
102
103

### Make a user unfollow another user

- Params:
104
105
  - `follower`: The nickname of the follower
  - `followed`: The nickname of the followed
106
- Response:
107
  - "ok"
108

109
## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation`
Maxim Filippov's avatar
Maxim Filippov committed
110
111
112
113
114
115
116

### Toggle user activation

- Params:
  - `nickname`
- Response: User’s object

Sergey Suprunenko's avatar
Sergey Suprunenko committed
117
```json
Maxim Filippov's avatar
Maxim Filippov committed
118
{
Maxim Filippov's avatar
Maxim Filippov committed
119
120
121
  "deactivated": bool,
  "id": integer,
  "nickname": string
Maxim Filippov's avatar
Maxim Filippov committed
122
123
}
```
Haelwenn's avatar
Haelwenn committed
124

125
## `PUT /api/pleroma/admin/users/tag`
Maxim Filippov's avatar
Maxim Filippov committed
126

Haelwenn's avatar
Haelwenn committed
127
### Tag a list of users
Maxim Filippov's avatar
Maxim Filippov committed
128
129

- Params:
130
  - `nicknames` (array)
131
  - `tags` (array)
Maxim Filippov's avatar
Maxim Filippov committed
132

133
134
## `DELETE /api/pleroma/admin/users/tag`

Haelwenn's avatar
Haelwenn committed
135
### Untag a list of users
Maxim Filippov's avatar
Maxim Filippov committed
136
137

- Params:
138
  - `nicknames` (array)
139
  - `tags` (array)
Haelwenn's avatar
Haelwenn committed
140

141
## `GET /api/pleroma/admin/users/:nickname/permission_group`
Maxim Filippov's avatar
Maxim Filippov committed
142

Haelwenn's avatar
Haelwenn committed
143
### Get user user permission groups membership
Maxim Filippov's avatar
Maxim Filippov committed
144
145
146
147

- Params: none
- Response:

Sergey Suprunenko's avatar
Sergey Suprunenko committed
148
```json
Haelwenn's avatar
Haelwenn committed
149
{
Maxim Filippov's avatar
Maxim Filippov committed
150
151
  "is_moderator": bool,
  "is_admin": bool
Haelwenn's avatar
Haelwenn committed
152
153
154
}
```

155
## `GET /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
Maxim Filippov's avatar
Maxim Filippov committed
156

Haelwenn's avatar
Haelwenn committed
157
158
Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.

159
### Get user user permission groups membership per permission group
Maxim Filippov's avatar
Maxim Filippov committed
160
161
162
163

- Params: none
- Response:

Sergey Suprunenko's avatar
Sergey Suprunenko committed
164
```json
Haelwenn's avatar
Haelwenn committed
165
{
Maxim Filippov's avatar
Maxim Filippov committed
166
167
  "is_moderator": bool,
  "is_admin": bool
Haelwenn's avatar
Haelwenn committed
168
169
}
```
Maxim Filippov's avatar
Maxim Filippov committed
170

Maxim Filippov's avatar
Maxim Filippov committed
171
## DEPRECATED `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
172

Maxim Filippov's avatar
Maxim Filippov committed
173
### Add user to permission group
Maxim Filippov's avatar
Maxim Filippov committed
174
175
176
177

- Params: none
- Response:
  - On failure: `{"error": "…"}`
178
  - On success: JSON of the user
Maxim Filippov's avatar
Maxim Filippov committed
179

180
181
## `POST /api/pleroma/admin/users/permission_group/:permission_group`

Maxim Filippov's avatar
Maxim Filippov committed
182
### Add users to permission group
Maxim Filippov's avatar
Maxim Filippov committed
183

184
185
- Params:
  - `nicknames`: nicknames array
Maxim Filippov's avatar
Maxim Filippov committed
186
187
- Response:
  - On failure: `{"error": "…"}`
188
  - On success: JSON of the user
Maxim Filippov's avatar
Maxim Filippov committed
189

Maxim Filippov's avatar
Maxim Filippov committed
190
## DEPRECATED `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
Maxim Filippov's avatar
Maxim Filippov committed
191

192
193
## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`

Haelwenn's avatar
Haelwenn committed
194
### Remove user from permission group
Maxim Filippov's avatar
Maxim Filippov committed
195
196
197
198

- Params: none
- Response:
  - On failure: `{"error": "…"}`
199
  - On success: JSON of the user
Maxim Filippov's avatar
Maxim Filippov committed
200
- Note: An admin cannot revoke their own admin status.
Haelwenn's avatar
Haelwenn committed
201

Maxim Filippov's avatar
Maxim Filippov committed
202
203
204
205
## `DELETE /api/pleroma/admin/users/permission_group/:permission_group`

### Remove users from permission group

206
207
- Params:
  - `nicknames`: nicknames array
Maxim Filippov's avatar
Maxim Filippov committed
208
209
- Response:
  - On failure: `{"error": "…"}`
210
  - On success: JSON of the user
Maxim Filippov's avatar
Maxim Filippov committed
211
- Note: An admin cannot revoke their own admin status.
Haelwenn's avatar
Haelwenn committed
212

213
## `PATCH /api/pleroma/admin/users/activate`
214

215
### Activate user
Maxim Filippov's avatar
Maxim Filippov committed
216
217

- Params:
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
  - `nicknames`: nicknames array
- Response:

```json
{
  users: [
    {
      // user object
    }
  ]
}
```

## `PATCH /api/pleroma/admin/users/deactivate`

### Deactivate user

235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
- Params:
  - `nicknames`: nicknames array
- Response:

```json
{
  users: [
    {
      // user object
    }
  ]
}
```

## `PATCH /api/pleroma/admin/users/approve`

### Approve user

253
254
255
256
257
258
259
260
261
262
263
264
265
- Params:
  - `nicknames`: nicknames array
- Response:

```json
{
  users: [
    {
      // user object
    }
  ]
}
```
266

267
## `GET /api/pleroma/admin/users/:nickname_or_id`
268
269
270
271

### Retrive the details of a user

- Params:
Maxim Filippov's avatar
Maxim Filippov committed
272
  - `nickname` or `id`
273
274
275
276
- Response:
  - On failure: `Not found`
  - On success: JSON of the user

277
## `GET /api/pleroma/admin/users/:nickname_or_id/statuses`
278
279
280
281
282
283

### Retrive user's latest statuses

- Params:
  - `nickname` or `id`
  - *optional* `page_size`: number of statuses to return (default is `20`)
284
  - *optional* `godmode`: `true`/`false` – allows to see private statuses
285
  - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
286
287
288
289
- Response:
  - On failure: `Not found`
  - On success: JSON array of user's latest statuses

290
291
292
293
294
295
296
297
298
299
300
301
302
## `GET /api/pleroma/admin/instances/:instance/statuses`

### Retrive instance's latest statuses

- Params:
  - `instance`: instance name
  - *optional* `page_size`: number of statuses to return (default is `20`)
  - *optional* `godmode`: `true`/`false` – allows to see private statuses
  - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
- Response:
  - On failure: `Not found`
  - On success: JSON array of instance's latest statuses

303
304
305
306
307
308
309
310
311
312
313
314
315
## `GET /api/pleroma/admin/statuses`

### Retrives all latest statuses

- Params:
  - *optional* `page_size`: number of statuses to return (default is `20`)
  - *optional* `local_only`: excludes remote statuses
  - *optional* `godmode`: `true`/`false` – allows to see private statuses
  - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
- Response:
  - On failure: `Not found`
  - On success: JSON array of user's latest statuses

316
## `POST /api/pleroma/admin/relay`
Maxim Filippov's avatar
Maxim Filippov committed
317

Haelwenn's avatar
Haelwenn committed
318
### Follow a Relay
Maxim Filippov's avatar
Maxim Filippov committed
319
320
321
322
323
324

- Params:
  - `relay_url`
- Response:
  - On success: URL of the followed relay

325
326
## `DELETE /api/pleroma/admin/relay`

Haelwenn's avatar
Haelwenn committed
327
### Unfollow a Relay
Maxim Filippov's avatar
Maxim Filippov committed
328
329
330
331
332

- Params:
  - `relay_url`
- Response:
  - On success: URL of the unfollowed relay
Haelwenn's avatar
Haelwenn committed
333

334
335
336
337
338
339
340
341
## `GET /api/pleroma/admin/relay`

### List Relays

- Params: none
- Response:
  - On success: JSON array of relays

342
## `POST /api/pleroma/admin/users/invite_token`
Maxim Filippov's avatar
Maxim Filippov committed
343

Alexander Strizhakov's avatar
namings    
Alexander Strizhakov committed
344
### Create an account registration invite token
Maxim Filippov's avatar
Maxim Filippov committed
345

346
- Params:
Alexander Strizhakov's avatar
Alexander Strizhakov committed
347
348
  - *optional* `max_use` (integer)
  - *optional* `expires_at` (date string e.g. "2019-04-07")
349
350
351
352
353
354
355
356
357
358
359
360
361
- Response:

```json
{
  "id": integer,
  "token": string,
  "used": boolean,
  "expires_at": date,
  "uses": integer,
  "max_use": integer,
  "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
}
```
Haelwenn's avatar
Haelwenn committed
362

363
## `GET /api/pleroma/admin/users/invites`
364
365
366
367
368
369

### Get a list of generated invites

- Params: none
- Response:

Sergey Suprunenko's avatar
Sergey Suprunenko committed
370
```json
371
372
373
374
375
376
377
{

  "invites": [
    {
      "id": integer,
      "token": string,
      "used": boolean,
378
      "expires_at": date,
379
380
381
382
383
384
385
386
387
      "uses": integer,
      "max_use": integer,
      "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
    },
    ...
  ]
}
```

388
## `POST /api/pleroma/admin/users/revoke_invite`
389
390
391
392
393
394
395

### Revoke invite by token

- Params:
  - `token`
- Response:

Sergey Suprunenko's avatar
Sergey Suprunenko committed
396
```json
397
398
399
400
{
  "id": integer,
  "token": string,
  "used": boolean,
401
  "expires_at": date,
402
403
404
405
406
407
408
  "uses": integer,
  "max_use": integer,
  "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)

}
```

409
## `POST /api/pleroma/admin/users/email_invite`
Maxim Filippov's avatar
Maxim Filippov committed
410

Haelwenn's avatar
Haelwenn committed
411
### Sends registration invite via email
Maxim Filippov's avatar
Maxim Filippov committed
412
413
414

- Params:
  - `email`
415
  - `name`, optional
Haelwenn's avatar
Haelwenn committed
416

417
418
419
420
421
422
423
424
- Response:
  - On success: `204`, empty response
  - On failure:
    - 400 Bad Request, JSON:

    ```json
      [
        {
425
          "error": "Appropriate error message here"
426
427
428
429
        }
      ]
    ```

430
## `GET /api/pleroma/admin/users/:nickname/password_reset`
Maxim Filippov's avatar
Maxim Filippov committed
431

Haelwenn's avatar
Haelwenn committed
432
### Get a password reset token for a given nickname
Maxim Filippov's avatar
Maxim Filippov committed
433

434

Maxim Filippov's avatar
Maxim Filippov committed
435
- Params: none
Maxim Filippov's avatar
Maxim Filippov committed
436
437
438
439
- Response:

```json
{
440
441
  "token": "base64 reset token",
  "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token"
Maxim Filippov's avatar
Maxim Filippov committed
442
443
444
}
```

445
## `PATCH /api/pleroma/admin/users/force_password_reset`
446
447
448

### Force passord reset for a user with a given nickname

Maxim Filippov's avatar
Maxim Filippov committed
449
450
- Params:
  - `nicknames`
451
452
- Response: none (code `204`)

453
454
455
456
457
458
459
460
## PUT `/api/pleroma/admin/users/disable_mfa`

### Disable mfa for user's account.

- Params:
  - `nickname`
- Response: User’s nickname

461
## `GET /api/pleroma/admin/users/:nickname/credentials`
462

463
### Get the user's email, password, display and settings-related fields
464
465

- Params:
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
  - `nickname`

- Response:

```json
{
  "actor_type": "Person",
  "allow_following_move": true,
  "avatar": "https://pleroma.social/media/7e8e7508fd545ef580549b6881d80ec0ff2c81ed9ad37b9bdbbdf0e0d030159d.jpg",
  "background": "https://pleroma.social/media/4de34c0bd10970d02cbdef8972bef0ebbf55f43cadc449554d4396156162fe9a.jpg",
  "banner": "https://pleroma.social/media/8d92ba2bd244b613520abf557dd448adcd30f5587022813ee9dd068945986946.jpg",
  "bio": "bio",
  "default_scope": "public",
  "discoverable": false,
  "email": "user@example.com",
  "fields": [
    {
      "name": "example",
      "value": "<a href=\"https://example.com\" rel=\"ugc\">https://example.com</a>"
    }
  ],
  "hide_favorites": false,
  "hide_followers": false,
  "hide_followers_count": false,
  "hide_follows": false,
  "hide_follows_count": false,
  "id": "9oouHaEEUR54hls968",
  "locked": true,
  "name": "user",
  "no_rich_text": true,
  "pleroma_settings_store": {},
  "raw_fields": [
    {
      "id": 1,
      "name": "example",
      "value": "https://example.com"
    },
  ],
  "show_role": true,
  "skip_thread_containment": false
}
```

## `PATCH /api/pleroma/admin/users/:nickname/credentials`

### Change the user's email, password, display and settings-related fields

513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
* Params:
  * `email`
  * `password`
  * `name`
  * `bio`
  * `avatar`
  * `locked`
  * `no_rich_text`
  * `default_scope`
  * `banner`
  * `hide_follows`
  * `hide_followers`
  * `hide_followers_count`
  * `hide_follows_count`
  * `hide_favorites`
  * `allow_following_move`
  * `background`
  * `show_role`
  * `skip_thread_containment`
  * `fields`
  * `discoverable`
  * `actor_type`

* Responses:

Status: 200
Alexander Strizhakov's avatar
Alexander Strizhakov committed
539
540
541
542
543

```json
{"status": "success"}
```

544
545
Status: 400

Alexander Strizhakov's avatar
Alexander Strizhakov committed
546
547
548
549
550
551
552
553
```json
{"errors":
  {"actor_type": "is invalid"},
  {"email": "has invalid format"},
  ...
 }
```

554
555
Status: 404

Alexander Strizhakov's avatar
Alexander Strizhakov committed
556
```json
557
{"error": "Not found"}
Alexander Strizhakov's avatar
Alexander Strizhakov committed
558
```
559

560
561
## `GET /api/pleroma/admin/reports`

Sergey Suprunenko's avatar
Sergey Suprunenko committed
562
### Get a list of reports
563

Sergey Suprunenko's avatar
Sergey Suprunenko committed
564
- Params:
Maxim Filippov's avatar
Maxim Filippov committed
565
566
567
568
  - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
  - *optional* `limit`: **integer** the number of records to retrieve
  - *optional* `page`: **integer** page number
  - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
569
- Response:
Sergey Suprunenko's avatar
Sergey Suprunenko committed
570
571
572
573
574
575
576
577
  - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
  - On success: JSON, returns a list of reports, where:
    - `account`: the user who has been reported
    - `actor`: the user who has sent the report
    - `statuses`: list of statuses that have been included to the report

```json
{
578
  "total" : 1,
Sergey Suprunenko's avatar
Sergey Suprunenko committed
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
  "reports": [
    {
      "account": {
        "acct": "user",
        "avatar": "https://pleroma.example.org/images/avi.png",
        "avatar_static": "https://pleroma.example.org/images/avi.png",
        "bot": false,
        "created_at": "2019-04-23T17:32:04.000Z",
        "display_name": "User",
        "emojis": [],
        "fields": [],
        "followers_count": 1,
        "following_count": 1,
        "header": "https://pleroma.example.org/images/banner.png",
        "header_static": "https://pleroma.example.org/images/banner.png",
        "id": "9i6dAJqSGSKMzLG2Lo",
        "locked": false,
        "note": "",
        "pleroma": {
          "confirmation_pending": false,
          "hide_favorites": true,
          "hide_followers": false,
          "hide_follows": false,
          "is_admin": false,
          "is_moderator": false,
          "relationship": {},
          "tags": []
        },
        "source": {
          "note": "",
          "pleroma": {},
          "sensitive": false
        },
612
        "tags": ["force_unlisted"],
Sergey Suprunenko's avatar
Sergey Suprunenko committed
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
        "statuses_count": 3,
        "url": "https://pleroma.example.org/users/user",
        "username": "user"
      },
      "actor": {
        "acct": "lain",
        "avatar": "https://pleroma.example.org/images/avi.png",
        "avatar_static": "https://pleroma.example.org/images/avi.png",
        "bot": false,
        "created_at": "2019-03-28T17:36:03.000Z",
        "display_name": "Roger Braun",
        "emojis": [],
        "fields": [],
        "followers_count": 1,
        "following_count": 1,
        "header": "https://pleroma.example.org/images/banner.png",
        "header_static": "https://pleroma.example.org/images/banner.png",
        "id": "9hEkA5JsvAdlSrocam",
        "locked": false,
        "note": "",
        "pleroma": {
          "confirmation_pending": false,
          "hide_favorites": false,
          "hide_followers": false,
          "hide_follows": false,
          "is_admin": false,
          "is_moderator": false,
          "relationship": {},
          "tags": []
        },
        "source": {
          "note": "",
          "pleroma": {},
          "sensitive": false
        },
648
        "tags": ["force_unlisted"],
Sergey Suprunenko's avatar
Sergey Suprunenko committed
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
        "statuses_count": 1,
        "url": "https://pleroma.example.org/users/lain",
        "username": "lain"
      },
      "content": "Please delete it",
      "created_at": "2019-04-29T19:48:15.000Z",
      "id": "9iJGOv1j8hxuw19bcm",
      "state": "open",
      "statuses": [
        {
          "account": { ... },
          "application": {
            "name": "Web",
            "website": null
          },
          "bookmarked": false,
          "card": null,
          "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>",
          "created_at": "2019-04-23T19:15:47.000Z",
          "emojis": [],
          "favourited": false,
          "favourites_count": 0,
          "id": "9i6mQ9uVrrOmOime8m",
          "in_reply_to_account_id": null,
          "in_reply_to_id": null,
          "language": null,
          "media_attachments": [],
          "mentions": [
            {
              "acct": "lain",
              "id": "9hEkA5JsvAdlSrocam",
              "url": "https://pleroma.example.org/users/lain",
              "username": "lain"
            },
            {
              "acct": "user",
              "id": "9i6dAJqSGSKMzLG2Lo",
              "url": "https://pleroma.example.org/users/user",
              "username": "user"
            }
          ],
          "muted": false,
          "pinned": false,
          "pleroma": {
            "content": {
              "text/plain": "@lain click on my link https://www.google.com/"
            },
            "conversation_id": 28,
            "in_reply_to_account_acct": null,
            "local": true,
            "spoiler_text": {
              "text/plain": ""
            }
          },
          "reblog": null,
          "reblogged": false,
          "reblogs_count": 0,
          "replies_count": 0,
          "sensitive": false,
          "spoiler_text": "",
          "tags": [],
          "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
          "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
          "visibility": "direct"
        }
      ]
    }
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
  ]
}
```

## `GET /api/pleroma/admin/grouped_reports`

### Get a list of reports, grouped by status

- Params: none
- On success: JSON, returns a list of reports, where:
  - `date`: date of the latest report
  - `account`: the user who has been reported (see `/api/pleroma/admin/reports` for reference)
  - `status`: reported status (see `/api/pleroma/admin/reports` for reference)
  - `actors`: users who had reported this status (see `/api/pleroma/admin/reports` for reference)
  - `reports`: reports (see `/api/pleroma/admin/reports` for reference)

```json
  "reports": [
734
    {
735
736
737
738
      "date": "2019-10-07T12:31:39.615149Z",
      "account": { ... },
      "status": { ... },
      "actors": [{ ... }, { ... }],
739
740
      "reports": [{ ... }]
    }
Sergey Suprunenko's avatar
Sergey Suprunenko committed
741
742
743
  ]
```

744
745
## `GET /api/pleroma/admin/reports/:id`

Sergey Suprunenko's avatar
Sergey Suprunenko committed
746
### Get an individual report
747

Sergey Suprunenko's avatar
Sergey Suprunenko committed
748
749
750
- Params:
  - `id`
- Response:
751
  - On failure:
Sergey Suprunenko's avatar
Sergey Suprunenko committed
752
753
754
755
    - 403 Forbidden `{"error": "error_msg"}`
    - 404 Not Found `"Not found"`
  - On success: JSON, Report object (see above)

756
757
758
759
## `PATCH /api/pleroma/admin/reports`

### Change the state of one or multiple reports

Sergey Suprunenko's avatar
Sergey Suprunenko committed
760
- Params:
761
762
763
764
765
766
767
768
769
770
771

```json
  `reports`: [
    {
      `id`, // required, report id
      `state` // required, the new state. Valid values are `open`, `closed` and `resolved`
    },
    ...
  ]
```

772
773
- Response:
  - On failure:
774
775
776
777
778
779
780
781
782
783
784
785
786
    - 400 Bad Request, JSON:

    ```json
      [
        {
          `id`, // report id
          `error` // error message
        }
      ]
    ```

  - On success: `204`, empty response

Maxim Filippov's avatar
Maxim Filippov committed
787
## `POST /api/pleroma/admin/reports/:id/notes`
Sergey Suprunenko's avatar
Sergey Suprunenko committed
788

Maxim Filippov's avatar
Docs    
Maxim Filippov committed
789
### Create report note
790

Sergey Suprunenko's avatar
Sergey Suprunenko committed
791
- Params:
Maxim Filippov's avatar
Docs    
Maxim Filippov committed
792
  - `id`: required, report id
Maxim Filippov's avatar
Maxim Filippov committed
793
  - `content`: required, the message
794
795
796
- Response:
  - On failure:
    - 400 Bad Request `"Invalid parameters"` when `status` is missing
Maxim Filippov's avatar
Maxim Filippov committed
797
  - On success: `204`, empty response
Sergey Suprunenko's avatar
Sergey Suprunenko committed
798

799
## `DELETE /api/pleroma/admin/reports/:report_id/notes/:id`
Maxim Filippov's avatar
Docs    
Maxim Filippov committed
800
801
802
803
804
805
806
807
808
809
810

### Delete report note

- Params:
  - `report_id`: required, report id
  - `id`: required, note id
- Response:
  - On failure:
    - 400 Bad Request `"Invalid parameters"` when `status` is missing
  - On success: `204`, empty response

811
812
813
814
815
816
817
818
819
820
821
## `GET /api/pleroma/admin/statuses/:id`

### Show status by id

- Params:
  - `id`: required, status id
- Response:
  - On failure:
    - 404 Not Found `"Not Found"`
  - On success: JSON, Mastodon Status entity

822
823
## `PUT /api/pleroma/admin/statuses/:id`

Sergey Suprunenko's avatar
Sergey Suprunenko committed
824
### Change the scope of an individual reported status
825

Sergey Suprunenko's avatar
Sergey Suprunenko committed
826
827
828
829
- Params:
  - `id`
  - `sensitive`: optional, valid values are `true` or `false`
  - `visibility`: optional, valid values are `public`, `private` and `unlisted`
830
831
- Response:
  - On failure:
Sergey Suprunenko's avatar
Sergey Suprunenko committed
832
    - 400 Bad Request `"Unsupported visibility"`
833
    - 403 Forbidden `{"error": "error_msg"}`
Sergey Suprunenko's avatar
Sergey Suprunenko committed
834
835
836
    - 404 Not Found `"Not found"`
  - On success: JSON, Mastodon Status entity

837
838
## `DELETE /api/pleroma/admin/statuses/:id`

Sergey Suprunenko's avatar
Sergey Suprunenko committed
839
### Delete an individual reported status
840

Sergey Suprunenko's avatar
Sergey Suprunenko committed
841
842
- Params:
  - `id`
843
844
845
- Response:
  - On failure:
    - 403 Forbidden `{"error": "error_msg"}`
Sergey Suprunenko's avatar
Sergey Suprunenko committed
846
847
    - 404 Not Found `"Not found"`
  - On success: 200 OK `{}`
848

Alexander Strizhakov's avatar
Alexander Strizhakov committed
849
850
851
852
## `GET /api/pleroma/admin/restart`

### Restarts pleroma application

853
854
**Only works when configuration from database is enabled.**

Alexander Strizhakov's avatar
Alexander Strizhakov committed
855
856
857
858
- Params: none
- Response:
  - On failure:
    - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
Alexander Strizhakov's avatar
Alexander Strizhakov committed
859
860
861
862
863

```json
{}
```

864
865
866
867
868
869
870
871
872
873
874
875
876
## `GET /api/pleroma/admin/need_reboot`

### Returns the flag whether the pleroma should be restarted

- Params: none
- Response:
  - `need_reboot` - boolean
```json
{
  "need_reboot": false
}
```

877
878
## `GET /api/pleroma/admin/config`

Alexander Strizhakov's avatar
Alexander Strizhakov committed
879
### Get list of merged default settings with saved in database.
880

881
*If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
Alexander Strizhakov's avatar
Alexander Strizhakov committed
882

883
**Only works when configuration from database is enabled.**
884

Alexander Strizhakov's avatar
Alexander Strizhakov committed
885
886
- Params:
  - `only_db`: true (*optional*, get only saved in database settings)
887
- Response:
Alexander Strizhakov's avatar
Alexander Strizhakov committed
888
  - On failure:
Alexander Strizhakov's avatar
Alexander Strizhakov committed
889
    - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
890
891
892

```json
{
Alexander Strizhakov's avatar
Alexander Strizhakov committed
893
  "configs": [
894
    {
895
896
897
      "group": ":pleroma",
      "key": "Pleroma.Upload",
      "value": []
898
     }
Alexander Strizhakov's avatar
Alexander Strizhakov committed
899
900
  ],
  "need_reboot": true
901
902
903
}
```

904
905
## `POST /api/pleroma/admin/config`

906
### Update config settings
907

908
*If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
Alexander Strizhakov's avatar
Alexander Strizhakov committed
909

910
**Only works when configuration from database is enabled.**
911
912

Some modifications are necessary to save the config settings correctly:
913

914
915
916
917
918
919
920
921
922
- strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules;
```
"Pleroma.Upload" -> Pleroma.Upload
"Oban" -> Oban
```
- strings starting with `:` will be converted to atoms;
```
":pleroma" -> :pleroma
```
Alexander Strizhakov's avatar
Alexander Strizhakov committed
923
- objects with `tuple` key and array value will be converted to tuples;
924
925
926
```
{"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []}
```
Alexander Strizhakov's avatar
Alexander Strizhakov committed
927
- arrays with *tuple objects* will be converted to keywords;
928
929
930
```
[{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"]
```
Alexander Strizhakov's avatar
Alexander Strizhakov committed
931

932
933
Most of the settings will be applied in `runtime`, this means that you don't need to restart the instance. But some settings are applied in `compile time` and require a reboot of the instance, such as:
- all settings inside these keys:
934
  - `:hackney_pools`
Alexander Strizhakov's avatar
Alexander Strizhakov committed
935
936
  - `:connections_pool`
  - `:pools`
937
  - `:chat`
938
939
940
941
- partially settings inside these keys:
  - `:seconds_valid` in `Pleroma.Captcha`
  - `:proxy_remote` in `Pleroma.Upload`
  - `:upload_limit` in `:instance`
942
943

- Params:
944
945
946
947
948
949
950
951
952
953
954
955
956
957
  - `configs` - array of config objects
  - config object params:
    - `group` - string (**required**)
    - `key` - string (**required**)
    - `value` - string, [], {} or {"tuple": []} (**required**)
    - `delete` - true (*optional*, if setting must be deleted)
    - `subkeys` - array of strings (*optional*, only works when `delete=true` parameter is passed, otherwise will be ignored)

*When a value have several nested settings, you can delete only some nested settings by passing a parameter `subkeys`, without deleting all settings by key.*
```
[subkey: val1, subkey2: val2, subkey3: val3] \\ initial value
{"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion
[subkey2: val2] \\ value after deletion
```
958

959
960
961
962
963
964
965
*Most of the settings can be partially updated through merge old values with new values, except settings value of which is list or is not keyword.*

Example of setting without keyword in value:
```elixir
config :tesla, :adapter, Tesla.Adapter.Hackney
```

Alexander Strizhakov's avatar
Alexander Strizhakov committed
966
List of settings which support only full update by key:
967
968
969
970
971
972
973
```elixir
@full_key_update [
    {:pleroma, :ecto_repos},
    {:quack, :meta},
    {:mime, :types},
    {:cors_plug, [:max_age, :methods, :expose, :headers]},
    {:auto_linker, :opts},
974
975
    {:swarm, :node_blacklist},
    {:logger, :backends}
976
977
978
  ]
```

Alexander Strizhakov's avatar
Alexander Strizhakov committed
979
980
981
982
983
984
985
986
987
988
989
List of settings which support only full update by subkey:
```elixir
@full_subkey_update [
    {:pleroma, :assets, :mascots},
    {:pleroma, :emoji, :groups},
    {:pleroma, :workers, :retries},
    {:pleroma, :mrf_subchain, :match_actor},
    {:pleroma, :mrf_keyword, :replace}
  ]
```

990
991
992
993
994
995
996
997
998
*Settings without explicit key must be sended in separate config object params.*
```elixir
config :quack,
  level: :debug,
  meta: [:all],
  ...
```
```json
{
Alexander Strizhakov's avatar
Alexander Strizhakov committed
999
  "configs": [
1000
    {"group": ":quack", "key": ":level", "value": ":debug"},
For faster browsing, not all history is shown. View entire blame