git.squeep.com Git - akkoma/blob - docs/development/API/admin_api.md

   1 # Admin API
   2
   3 Authentication is required and the user must be an admin.
   4
   5 Configuration options:
   6
   7 * `[:auth, :enforce_oauth_admin_scope_usage]` — OAuth admin scope requirement toggle.
   8     If `true`, admin actions explicitly demand admin OAuth scope(s) presence in OAuth token (client app must support admin scopes).
   9     If `false` and token doesn't have admin scope(s), `is_admin` user flag grants access to admin-specific actions.
  10     Note that client app needs to explicitly support admin scopes and request them when obtaining auth token.
  11
  12 ## `GET /api/pleroma/admin/users`
  13
  14 ### List users
  15
  16 - Query Params:
  17   - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
  18   - *optional* `filters`: **string** comma-separated string of filters:
  19     - `local`: only local users
  20     - `external`: only external users
  21     - `active`: only active users
  22     - `need_approval`: only unapproved users
  23     - `unconfirmed`: only unconfirmed users
  24     - `deactivated`: only deactivated users
  25     - `is_admin`: users with admin role
  26     - `is_moderator`: users with moderator role
  27   - *optional* `page`: **integer** page number
  28   - *optional* `page_size`: **integer** number of users per page (default is `50`)
  29   - *optional* `tags`: **[string]** tags list
  30   - *optional* `actor_types`: **[string]** actor type list (`Person`, `Service`, `Application`)
  31   - *optional* `name`: **string** user display name
  32   - *optional* `email`: **string** user email
  33 - 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`
  34 - Response:
  35
  36 ```json
  37 {
  38   "page_size": integer,
  39   "count": integer,
  40   "users": [
  41     {
  42       "deactivated": bool,
  43       "id": integer,
  44       "nickname": string,
  45       "roles": {
  46         "admin": bool,
  47         "moderator": bool
  48       },
  49       "local": bool,
  50       "tags": array,
  51       "avatar": string,
  52       "display_name": string,
  53       "confirmation_pending": bool,
  54       "approval_pending": bool,
  55       "registration_reason": string,
  56     },
  57     ...
  58   ]
  59 }
  60 ```
  61
  62 ## DEPRECATED `DELETE /api/pleroma/admin/users`
  63
  64 ### Remove a user
  65
  66 - Params:
  67   - `nickname`
  68 - Response: User’s nickname
  69
  70 ## `DELETE /api/pleroma/admin/users`
  71
  72 ### Remove a user
  73
  74 - Params:
  75   - `nicknames`
  76 - Response: Array of user nicknames
  77
  78 ### Create a user
  79
  80 - Method: `POST`
  81 - Params:
  82   `users`: [
  83     {
  84       `nickname`,
  85       `email`,
  86       `password`
  87     }
  88   ]
  89 - Response: User’s nickname
  90
  91 ## `POST /api/pleroma/admin/users/follow`
  92
  93 ### Make a user follow another user
  94
  95 - Params:
  96   - `follower`: The nickname of the follower
  97   - `followed`: The nickname of the followed
  98 - Response:
  99   - "ok"
 100
 101 ## `POST /api/pleroma/admin/users/unfollow`
 102
 103 ### Make a user unfollow another user
 104
 105 - Params:
 106   - `follower`: The nickname of the follower
 107   - `followed`: The nickname of the followed
 108 - Response:
 109   - "ok"
 110
 111 ## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation`
 112
 113 ### Toggle user activation
 114
 115 - Params:
 116   - `nickname`
 117 - Response: User’s object
 118
 119 ```json
 120 {
 121   "deactivated": bool,
 122   "id": integer,
 123   "nickname": string
 124 }
 125 ```
 126
 127 ## `PUT /api/pleroma/admin/users/tag`
 128
 129 ### Tag a list of users
 130
 131 - Params:
 132   - `nicknames` (array)
 133   - `tags` (array)
 134
 135 ## `DELETE /api/pleroma/admin/users/tag`
 136
 137 ### Untag a list of users
 138
 139 - Params:
 140   - `nicknames` (array)
 141   - `tags` (array)
 142
 143 ## `GET /api/pleroma/admin/users/:nickname/permission_group`
 144
 145 ### Get user user permission groups membership
 146
 147 - Params: none
 148 - Response:
 149
 150 ```json
 151 {
 152   "is_moderator": bool,
 153   "is_admin": bool
 154 }
 155 ```
 156
 157 ## `GET /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
 158
 159 Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
 160
 161 ### Get user user permission groups membership per permission group
 162
 163 - Params: none
 164 - Response:
 165
 166 ```json
 167 {
 168   "is_moderator": bool,
 169   "is_admin": bool
 170 }
 171 ```
 172
 173 ## DEPRECATED `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
 174
 175 ### Add user to permission group
 176
 177 - Params: none
 178 - Response:
 179   - On failure: `{"error": "…"}`
 180   - On success: JSON of the user
 181
 182 ## `POST /api/pleroma/admin/users/permission_group/:permission_group`
 183
 184 ### Add users to permission group
 185
 186 - Params:
 187   - `nicknames`: nicknames array
 188 - Response:
 189   - On failure: `{"error": "…"}`
 190   - On success: JSON of the user
 191
 192 ## DEPRECATED `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
 193
 194 ## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
 195
 196 ### Remove user from permission group
 197
 198 - Params: none
 199 - Response:
 200   - On failure: `{"error": "…"}`
 201   - On success: JSON of the user
 202 - Note: An admin cannot revoke their own admin status.
 203
 204 ## `DELETE /api/pleroma/admin/users/permission_group/:permission_group`
 205
 206 ### Remove users from permission group
 207
 208 - Params:
 209   - `nicknames`: nicknames array
 210 - Response:
 211   - On failure: `{"error": "…"}`
 212   - On success: JSON of the user
 213 - Note: An admin cannot revoke their own admin status.
 214
 215 ## `PATCH /api/pleroma/admin/users/activate`
 216
 217 ### Activate user
 218
 219 - Params:
 220   - `nicknames`: nicknames array
 221 - Response:
 222
 223 ```json
 224 {
 225   users: [
 226     {
 227       // user object
 228     }
 229   ]
 230 }
 231 ```
 232
 233 ## `PATCH /api/pleroma/admin/users/deactivate`
 234
 235 ### Deactivate user
 236
 237 - Params:
 238   - `nicknames`: nicknames array
 239 - Response:
 240
 241 ```json
 242 {
 243   users: [
 244     {
 245       // user object
 246     }
 247   ]
 248 }
 249 ```
 250
 251 ## `PATCH /api/pleroma/admin/users/approve`
 252
 253 ### Approve user
 254
 255 - Params:
 256   - `nicknames`: nicknames array
 257 - Response:
 258
 259 ```json
 260 {
 261   users: [
 262     {
 263       // user object
 264     }
 265   ]
 266 }
 267 ```
 268
 269 ## `GET /api/pleroma/admin/users/:nickname_or_id`
 270
 271 ### Retrive the details of a user
 272
 273 - Params:
 274   - `nickname` or `id`
 275 - Response:
 276   - On failure: `Not found`
 277   - On success: JSON of the user
 278
 279 ## `GET /api/pleroma/admin/users/:nickname_or_id/statuses`
 280
 281 ### Retrive user's latest statuses
 282
 283 - Params:
 284   - `nickname` or `id`
 285   - *optional* `page_size`: number of statuses to return (default is `20`)
 286   - *optional* `godmode`: `true`/`false` – allows to see private statuses
 287   - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
 288 - Response:
 289   - On failure: `Not found`
 290  - On success: JSON, where:
 291     - `total`: total count of the statuses for the user
 292     - `activities`: list of the statuses for the user
 293
 294 ```json
 295 {
 296   "total" : 1,
 297   "activities": [
 298     // activities list
 299   ]
 300 }
 301 ```
 302
 303 ## `GET /api/pleroma/admin/instances/:instance/statuses`
 304
 305 ### Retrive instance's latest statuses
 306
 307 - Params:
 308   - `instance`: instance name
 309   - *optional* `page_size`: number of statuses to return (default is `20`)
 310   - *optional* `godmode`: `true`/`false` – allows to see private statuses
 311   - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
 312 - Response:
 313   - On failure: `Not found`
 314   - On success: JSON array of instance's latest statuses
 315
 316 ## `GET /api/pleroma/admin/statuses`
 317
 318 ### Retrives all latest statuses
 319
 320 - Params:
 321   - *optional* `page_size`: number of statuses to return (default is `20`)
 322   - *optional* `local_only`: excludes remote statuses
 323   - *optional* `godmode`: `true`/`false` – allows to see private statuses
 324   - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
 325 - Response:
 326   - On failure: `Not found`
 327   - On success: JSON array of user's latest statuses
 328
 329 ## `GET /api/pleroma/admin/relay`
 330
 331 ### List Relays
 332
 333 Params: none
 334 Response:
 335
 336 * On success: JSON array of relays
 337
 338 ```json
 339 [
 340   {"actor": "https://example.com/relay", "followed_back": true},
 341   {"actor": "https://example2.com/relay", "followed_back": false}
 342 ]
 343 ```
 344
 345 ## `POST /api/pleroma/admin/relay`
 346
 347 ### Follow a Relay
 348
 349 Params:
 350
 351 * `relay_url`
 352
 353 Response:
 354
 355 * On success: relay json object
 356
 357 ```json
 358 {"actor": "https://example.com/relay", "followed_back": true}
 359 ```
 360
 361 ## `DELETE /api/pleroma/admin/relay`
 362
 363 ### Unfollow a Relay
 364
 365 - Params:
 366   - `relay_url`
 367   - *optional* `force`: forcefully unfollow a relay even when the relay is not available. (default is `false`)
 368
 369 Response:
 370
 371 * On success: URL of the unfollowed relay
 372
 373 ```json
 374 {"https://example.com/relay"}
 375 ```
 376
 377 ## `POST /api/pleroma/admin/users/invite_token`
 378
 379 ### Create an account registration invite token
 380
 381 - Params:
 382   - *optional* `max_use` (integer)
 383   - *optional* `expires_at` (date string e.g. "2019-04-07")
 384 - Response:
 385
 386 ```json
 387 {
 388   "id": integer,
 389   "token": string,
 390   "used": boolean,
 391   "expires_at": date,
 392   "uses": integer,
 393   "max_use": integer,
 394   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 395 }
 396 ```
 397
 398 ## `GET /api/pleroma/admin/users/invites`
 399
 400 ### Get a list of generated invites
 401
 402 - Params: none
 403 - Response:
 404
 405 ```json
 406 {
 407
 408   "invites": [
 409     {
 410       "id": integer,
 411       "token": string,
 412       "used": boolean,
 413       "expires_at": date,
 414       "uses": integer,
 415       "max_use": integer,
 416       "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 417     },
 418     ...
 419   ]
 420 }
 421 ```
 422
 423 ## `POST /api/pleroma/admin/users/revoke_invite`
 424
 425 ### Revoke invite by token
 426
 427 - Params:
 428   - `token`
 429 - Response:
 430
 431 ```json
 432 {
 433   "id": integer,
 434   "token": string,
 435   "used": boolean,
 436   "expires_at": date,
 437   "uses": integer,
 438   "max_use": integer,
 439   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 440
 441 }
 442 ```
 443
 444 ## `POST /api/pleroma/admin/users/email_invite`
 445
 446 ### Sends registration invite via email
 447
 448 - Params:
 449   - `email`
 450   - `name`, optional
 451
 452 - Response:
 453   - On success: `204`, empty response
 454   - On failure:
 455     - 400 Bad Request, JSON:
 456
 457     ```json
 458       [
 459         {
 460           "error": "Appropriate error message here"
 461         }
 462       ]
 463     ```
 464
 465 ## `GET /api/pleroma/admin/users/:nickname/password_reset`
 466
 467 ### Get a password reset token for a given nickname
 468
 469
 470 - Params: none
 471 - Response:
 472
 473 ```json
 474 {
 475   "token": "base64 reset token",
 476   "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token"
 477 }
 478 ```
 479
 480 ## `PATCH /api/pleroma/admin/users/force_password_reset`
 481
 482 ### Force passord reset for a user with a given nickname
 483
 484 - Params:
 485   - `nicknames`
 486 - Response: none (code `204`)
 487
 488 ## PUT `/api/pleroma/admin/users/disable_mfa`
 489
 490 ### Disable mfa for user's account.
 491
 492 - Params:
 493   - `nickname`
 494 - Response: User’s nickname
 495
 496 ## `GET /api/pleroma/admin/users/:nickname/credentials`
 497
 498 ### Get the user's email, password, display and settings-related fields
 499
 500 - Params:
 501   - `nickname`
 502
 503 - Response:
 504
 505 ```json
 506 {
 507   "actor_type": "Person",
 508   "allow_following_move": true,
 509   "avatar": "https://pleroma.social/media/7e8e7508fd545ef580549b6881d80ec0ff2c81ed9ad37b9bdbbdf0e0d030159d.jpg",
 510   "background": "https://pleroma.social/media/4de34c0bd10970d02cbdef8972bef0ebbf55f43cadc449554d4396156162fe9a.jpg",
 511   "banner": "https://pleroma.social/media/8d92ba2bd244b613520abf557dd448adcd30f5587022813ee9dd068945986946.jpg",
 512   "bio": "bio",
 513   "default_scope": "public",
 514   "discoverable": false,
 515   "email": "user@example.com",
 516   "fields": [
 517     {
 518       "name": "example",
 519       "value": "<a href=\"https://example.com\" rel=\"ugc\">https://example.com</a>"
 520     }
 521   ],
 522   "hide_favorites": false,
 523   "hide_followers": false,
 524   "hide_followers_count": false,
 525   "hide_follows": false,
 526   "hide_follows_count": false,
 527   "id": "9oouHaEEUR54hls968",
 528   "locked": true,
 529   "name": "user",
 530   "no_rich_text": true,
 531   "pleroma_settings_store": {},
 532   "raw_fields": [
 533     {
 534       "id": 1,
 535       "name": "example",
 536       "value": "https://example.com"
 537     },
 538   ],
 539   "show_role": true,
 540   "skip_thread_containment": false
 541 }
 542 ```
 543
 544 ## `PATCH /api/pleroma/admin/users/:nickname/credentials`
 545
 546 ### Change the user's email, password, display and settings-related fields
 547
 548 * Params:
 549   * `email`
 550   * `password`
 551   * `name`
 552   * `bio`
 553   * `avatar`
 554   * `locked`
 555   * `no_rich_text`
 556   * `default_scope`
 557   * `banner`
 558   * `hide_follows`
 559   * `hide_followers`
 560   * `hide_followers_count`
 561   * `hide_follows_count`
 562   * `hide_favorites`
 563   * `allow_following_move`
 564   * `background`
 565   * `show_role`
 566   * `skip_thread_containment`
 567   * `fields`
 568   * `is_discoverable`
 569   * `actor_type`
 570
 571 * Responses:
 572
 573 Status: 200
 574
 575 ```json
 576 {"status": "success"}
 577 ```
 578
 579 Status: 400
 580
 581 ```json
 582 {"errors":
 583   {"actor_type": "is invalid"},
 584   {"email": "has invalid format"},
 585   ...
 586  }
 587 ```
 588
 589 Status: 404
 590
 591 ```json
 592 {"error": "Not found"}
 593 ```
 594
 595 ## `GET /api/pleroma/admin/reports`
 596
 597 ### Get a list of reports
 598
 599 - Params:
 600   - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
 601   - *optional* `limit`: **integer** the number of records to retrieve
 602   - *optional* `page`: **integer** page number
 603   - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
 604 - Response:
 605   - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
 606   - On success: JSON, returns a list of reports, where:
 607     - `account`: the user who has been reported
 608     - `actor`: the user who has sent the report
 609     - `statuses`: list of statuses that have been included to the report
 610
 611 ```json
 612 {
 613   "total" : 1,
 614   "reports": [
 615     {
 616       "account": {
 617         "acct": "user",
 618         "avatar": "https://pleroma.example.org/images/avi.png",
 619         "avatar_static": "https://pleroma.example.org/images/avi.png",
 620         "bot": false,
 621         "created_at": "2019-04-23T17:32:04.000Z",
 622         "display_name": "User",
 623         "emojis": [],
 624         "fields": [],
 625         "followers_count": 1,
 626         "following_count": 1,
 627         "header": "https://pleroma.example.org/images/banner.png",
 628         "header_static": "https://pleroma.example.org/images/banner.png",
 629         "id": "9i6dAJqSGSKMzLG2Lo",
 630         "locked": false,
 631         "note": "",
 632         "pleroma": {
 633           "confirmation_pending": false,
 634           "hide_favorites": true,
 635           "hide_followers": false,
 636           "hide_follows": false,
 637           "is_admin": false,
 638           "is_moderator": false,
 639           "relationship": {},
 640           "tags": []
 641         },
 642         "source": {
 643           "note": "",
 644           "pleroma": {},
 645           "sensitive": false
 646         },
 647         "tags": ["force_unlisted"],
 648         "statuses_count": 3,
 649         "url": "https://pleroma.example.org/users/user",
 650         "username": "user"
 651       },
 652       "actor": {
 653         "acct": "lain",
 654         "avatar": "https://pleroma.example.org/images/avi.png",
 655         "avatar_static": "https://pleroma.example.org/images/avi.png",
 656         "bot": false,
 657         "created_at": "2019-03-28T17:36:03.000Z",
 658         "display_name": "Roger Braun",
 659         "emojis": [],
 660         "fields": [],
 661         "followers_count": 1,
 662         "following_count": 1,
 663         "header": "https://pleroma.example.org/images/banner.png",
 664         "header_static": "https://pleroma.example.org/images/banner.png",
 665         "id": "9hEkA5JsvAdlSrocam",
 666         "locked": false,
 667         "note": "",
 668         "pleroma": {
 669           "confirmation_pending": false,
 670           "hide_favorites": false,
 671           "hide_followers": false,
 672           "hide_follows": false,
 673           "is_admin": false,
 674           "is_moderator": false,
 675           "relationship": {},
 676           "tags": []
 677         },
 678         "source": {
 679           "note": "",
 680           "pleroma": {},
 681           "sensitive": false
 682         },
 683         "tags": ["force_unlisted"],
 684         "statuses_count": 1,
 685         "url": "https://pleroma.example.org/users/lain",
 686         "username": "lain"
 687       },
 688       "content": "Please delete it",
 689       "created_at": "2019-04-29T19:48:15.000Z",
 690       "id": "9iJGOv1j8hxuw19bcm",
 691       "state": "open",
 692       "statuses": [
 693         {
 694           "account": { ... },
 695           "application": {
 696             "name": "Web",
 697             "website": null
 698           },
 699           "bookmarked": false,
 700           "card": null,
 701           "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>",
 702           "created_at": "2019-04-23T19:15:47.000Z",
 703           "emojis": [],
 704           "favourited": false,
 705           "favourites_count": 0,
 706           "id": "9i6mQ9uVrrOmOime8m",
 707           "in_reply_to_account_id": null,
 708           "in_reply_to_id": null,
 709           "language": null,
 710           "media_attachments": [],
 711           "mentions": [
 712             {
 713               "acct": "lain",
 714               "id": "9hEkA5JsvAdlSrocam",
 715               "url": "https://pleroma.example.org/users/lain",
 716               "username": "lain"
 717             },
 718             {
 719               "acct": "user",
 720               "id": "9i6dAJqSGSKMzLG2Lo",
 721               "url": "https://pleroma.example.org/users/user",
 722               "username": "user"
 723             }
 724           ],
 725           "muted": false,
 726           "pinned": false,
 727           "pleroma": {
 728             "content": {
 729               "text/plain": "@lain click on my link https://www.google.com/"
 730             },
 731             "conversation_id": 28,
 732             "in_reply_to_account_acct": null,
 733             "local": true,
 734             "spoiler_text": {
 735               "text/plain": ""
 736             }
 737           },
 738           "reblog": null,
 739           "reblogged": false,
 740           "reblogs_count": 0,
 741           "replies_count": 0,
 742           "sensitive": false,
 743           "spoiler_text": "",
 744           "tags": [],
 745           "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
 746           "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
 747           "visibility": "direct"
 748         }
 749       ]
 750     }
 751   ]
 752 }
 753 ```
 754
 755 ## `GET /api/pleroma/admin/grouped_reports`
 756
 757 ### Get a list of reports, grouped by status
 758
 759 - Params: none
 760 - On success: JSON, returns a list of reports, where:
 761   - `date`: date of the latest report
 762   - `account`: the user who has been reported (see `/api/pleroma/admin/reports` for reference)
 763   - `status`: reported status (see `/api/pleroma/admin/reports` for reference)
 764   - `actors`: users who had reported this status (see `/api/pleroma/admin/reports` for reference)
 765   - `reports`: reports (see `/api/pleroma/admin/reports` for reference)
 766
 767 ```json
 768   "reports": [
 769     {
 770       "date": "2019-10-07T12:31:39.615149Z",
 771       "account": { ... },
 772       "status": { ... },
 773       "actors": [{ ... }, { ... }],
 774       "reports": [{ ... }]
 775     }
 776   ]
 777 ```
 778
 779 ## `GET /api/pleroma/admin/reports/:id`
 780
 781 ### Get an individual report
 782
 783 - Params:
 784   - `id`
 785 - Response:
 786   - On failure:
 787     - 403 Forbidden `{"error": "error_msg"}`
 788     - 404 Not Found `"Not found"`
 789   - On success: JSON, Report object (see above)
 790
 791 ## `PATCH /api/pleroma/admin/reports`
 792
 793 ### Change the state of one or multiple reports
 794
 795 - Params:
 796
 797 ```json
 798   `reports`: [
 799     {
 800       `id`, // required, report id
 801       `state` // required, the new state. Valid values are `open`, `closed` and `resolved`
 802     },
 803     ...
 804   ]
 805 ```
 806
 807 - Response:
 808   - On failure:
 809     - 400 Bad Request, JSON:
 810
 811     ```json
 812       [
 813         {
 814           `id`, // report id
 815           `error` // error message
 816         }
 817       ]
 818     ```
 819
 820   - On success: `204`, empty response
 821
 822 ## `POST /api/pleroma/admin/reports/:id/notes`
 823
 824 ### Create report note
 825
 826 - Params:
 827   - `id`: required, report id
 828   - `content`: required, the message
 829 - Response:
 830   - On failure:
 831     - 400 Bad Request `"Invalid parameters"` when `status` is missing
 832   - On success: `204`, empty response
 833
 834 ## `DELETE /api/pleroma/admin/reports/:report_id/notes/:id`
 835
 836 ### Delete report note
 837
 838 - Params:
 839   - `report_id`: required, report id
 840   - `id`: required, note id
 841 - Response:
 842   - On failure:
 843     - 400 Bad Request `"Invalid parameters"` when `status` is missing
 844   - On success: `204`, empty response
 845
 846 ## `GET /api/pleroma/admin/statuses/:id`
 847
 848 ### Show status by id
 849
 850 - Params:
 851   - `id`: required, status id
 852 - Response:
 853   - On failure:
 854     - 404 Not Found `"Not Found"`
 855   - On success: JSON, Mastodon Status entity
 856
 857 ## `PUT /api/pleroma/admin/statuses/:id`
 858
 859 ### Change the scope of an individual reported status
 860
 861 - Params:
 862   - `id`
 863   - `sensitive`: optional, valid values are `true` or `false`
 864   - `visibility`: optional, valid values are `public`, `private` and `unlisted`
 865 - Response:
 866   - On failure:
 867     - 400 Bad Request `"Unsupported visibility"`
 868     - 403 Forbidden `{"error": "error_msg"}`
 869     - 404 Not Found `"Not found"`
 870   - On success: JSON, Mastodon Status entity
 871
 872 ## `DELETE /api/pleroma/admin/statuses/:id`
 873
 874 ### Delete an individual reported status
 875
 876 - Params:
 877   - `id`
 878 - Response:
 879   - On failure:
 880     - 403 Forbidden `{"error": "error_msg"}`
 881     - 404 Not Found `"Not found"`
 882   - On success: 200 OK `{}`
 883
 884 ## `GET /api/pleroma/admin/restart`
 885
 886 ### Restarts pleroma application
 887
 888 **Only works when configuration from database is enabled.**
 889
 890 - Params: none
 891 - Response:
 892   - On failure:
 893     - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
 894
 895 ```json
 896 {}
 897 ```
 898
 899 ## `GET /api/pleroma/admin/need_reboot`
 900
 901 ### Returns the flag whether the pleroma should be restarted
 902
 903 - Params: none
 904 - Response:
 905   - `need_reboot` - boolean
 906 ```json
 907 {
 908   "need_reboot": false
 909 }
 910 ```
 911
 912 ## `GET /api/pleroma/admin/config`
 913
 914 ### Get list of merged default settings with saved in database.
 915
 916 *If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
 917
 918 **Only works when configuration from database is enabled.**
 919
 920 - Params:
 921   - `only_db`: true (*optional*, get only saved in database settings)
 922 - Response:
 923   - On failure:
 924     - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
 925
 926 ```json
 927 {
 928   "configs": [
 929     {
 930       "group": ":pleroma",
 931       "key": "Pleroma.Upload",
 932       "value": []
 933      }
 934   ],
 935   "need_reboot": true
 936 }
 937 ```
 938
 939 ## `POST /api/pleroma/admin/config`
 940
 941 ### Update config settings
 942
 943 *If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.*
 944
 945 **Only works when configuration from database is enabled.**
 946
 947 Some modifications are necessary to save the config settings correctly:
 948
 949 - strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules;
 950 ```
 951 "Pleroma.Upload" -> Pleroma.Upload
 952 "Oban" -> Oban
 953 ```
 954 - strings starting with `:` will be converted to atoms;
 955 ```
 956 ":pleroma" -> :pleroma
 957 ```
 958 - objects with `tuple` key and array value will be converted to tuples;
 959 ```
 960 {"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []}
 961 ```
 962 - arrays with *tuple objects* will be converted to keywords;
 963 ```
 964 [{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"]
 965 ```
 966
 967 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:
 968 - all settings inside these keys:
 969   - `:hackney_pools`
 970   - `:connections_pool`
 971   - `:pools`
 972   - `:chat`
 973 - partially settings inside these keys:
 974   - `:seconds_valid` in `Pleroma.Captcha`
 975   - `:proxy_remote` in `Pleroma.Upload`
 976   - `:upload_limit` in `:instance`
 977
 978 - Params:
 979   - `configs` - array of config objects
 980   - config object params:
 981     - `group` - string (**required**)
 982     - `key` - string (**required**)
 983     - `value` - string, [], {} or {"tuple": []} (**required**)
 984     - `delete` - true (*optional*, if setting must be deleted)
 985     - `subkeys` - array of strings (*optional*, only works when `delete=true` parameter is passed, otherwise will be ignored)
 986
 987 *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.*
 988 ```
 989 [subkey: val1, subkey2: val2, subkey3: val3] \\ initial value
 990 {"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion
 991 [subkey2: val2] \\ value after deletion
 992 ```
 993
 994 *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.*
 995
 996 Example of setting without keyword in value:
 997 ```elixir
 998 config :tesla, :adapter, Tesla.Adapter.Hackney
 999 ```
1000
1001 List of settings which support only full update by key:
1002 ```elixir
1003 @full_key_update [
1004     {:pleroma, :ecto_repos},
1005     {:quack, :meta},
1006     {:mime, :types},
1007     {:cors_plug, [:max_age, :methods, :expose, :headers]},
1008     {:auto_linker, :opts},
1009     {:swarm, :node_blacklist},
1010     {:logger, :backends}
1011   ]
1012 ```
1013
1014 List of settings which support only full update by subkey:
1015 ```elixir
1016 @full_subkey_update [
1017     {:pleroma, :assets, :mascots},
1018     {:pleroma, :emoji, :groups},
1019     {:pleroma, :workers, :retries},
1020     {:pleroma, :mrf_subchain, :match_actor},
1021     {:pleroma, :mrf_keyword, :replace}
1022   ]
1023 ```
1024
1025 *Settings without explicit key must be sended in separate config object params.*
1026 ```elixir
1027 config :quack,
1028   level: :debug,
1029   meta: [:all],
1030   ...
1031 ```
1032 ```json
1033 {
1034   "configs": [
1035     {"group": ":quack", "key": ":level", "value": ":debug"},
1036     {"group": ":quack", "key": ":meta", "value": [":all"]},
1037     ...
1038   ]
1039 }
1040 ```
1041 - Request:
1042
1043 ```json
1044 {
1045   "configs": [
1046     {
1047       "group": ":pleroma",
1048       "key": "Pleroma.Upload",
1049       "value": [
1050         {"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
1051         {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]},
1052         {"tuple": [":link_name", true]},
1053         {"tuple": [":proxy_remote", false]},
1054         {"tuple": [":proxy_opts", [
1055           {"tuple": [":redirect_on_failure", false]},
1056           {"tuple": [":max_body_length", 1048576]},
1057           {"tuple": [":http", [
1058             {"tuple": [":follow_redirect", true]},
1059             {"tuple": [":pool", ":upload"]},
1060           ]]}
1061         ]
1062         ]},
1063         {"tuple": [":dispatch", {
1064           "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []]
1065         }]}
1066       ]
1067     }
1068   ]
1069 }
1070 ```
1071
1072 - Response:
1073   - On failure:
1074     - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
1075 ```json
1076 {
1077   "configs": [
1078     {
1079       "group": ":pleroma",
1080       "key": "Pleroma.Upload",
1081       "value": [...]
1082      }
1083   ],
1084   "need_reboot": true
1085 }
1086 ```
1087
1088 ## ` GET /api/pleroma/admin/config/descriptions`
1089
1090 ### Get JSON with config descriptions.
1091 Loads json generated from `config/descriptions.exs`.
1092
1093 - Params: none
1094 - Response:
1095
1096 ```json
1097 [{
1098     "group": ":pleroma", // string
1099     "key": "ModuleName", // string
1100     "type": "group", // string or list with possible values,
1101     "description": "Upload general settings", // string
1102     "children": [
1103       {
1104         "key": ":uploader", // string or module name `Pleroma.Upload`
1105         "type": "module",
1106         "description": "Module which will be used for uploads",
1107         "suggestions": ["module1", "module2"]
1108       },
1109       {
1110         "key": ":filters",
1111         "type": ["list", "module"],
1112         "description": "List of filter modules for uploads",
1113         "suggestions": [
1114           "module1", "module2", "module3"
1115         ]
1116       }
1117     ]
1118 }]
1119 ```
1120
1121 ## `GET /api/pleroma/admin/moderation_log`
1122
1123 ### Get moderation log
1124
1125 - Params:
1126   - *optional* `page`: **integer** page number
1127   - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
1128   - *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`
1129   - *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
1130   - *optional* `user_id`: **integer** filter logs by actor's id
1131   - *optional* `search`: **string** search logs by the log message
1132 - Response:
1133
1134 ```json
1135 [
1136   {
1137     "id": 1234,
1138     "data": {
1139       "actor": {
1140         "id": 1,
1141         "nickname": "lain"
1142       },
1143       "action": "relay_follow"
1144     },
1145     "time": 1502812026, // timestamp
1146     "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
1147   }
1148 ]
1149 ```
1150
1151 ## `POST /api/pleroma/admin/reload_emoji`
1152
1153 ### Reload the instance's custom emoji
1154
1155 - Authentication: required
1156 - Params: None
1157 - Response: JSON, "ok" and 200 status
1158
1159 ## `PATCH /api/pleroma/admin/users/confirm_email`
1160
1161 ### Confirm users' emails
1162
1163 - Params:
1164   - `nicknames`
1165 - Response: Array of user nicknames
1166
1167 ## `PATCH /api/pleroma/admin/users/resend_confirmation_email`
1168
1169 ### Resend confirmation email
1170
1171 - Params:
1172   - `nicknames`
1173 - Response: Array of user nicknames
1174
1175 ## `GET /api/pleroma/admin/stats`
1176
1177 ### Stats
1178
1179 - Query Params:
1180   - *optional* `instance`: **string** instance hostname (without protocol) to get stats for
1181 - Example: `https://mypleroma.org/api/pleroma/admin/stats?instance=lain.com`
1182
1183 - Response:
1184
1185 ```json
1186 {
1187   "status_visibility": {
1188     "direct": 739,
1189     "private": 9,
1190     "public": 17,
1191     "unlisted": 14
1192   }
1193 }
1194 ```
1195
1196 ## `GET /api/pleroma/admin/oauth_app`
1197
1198 ### List OAuth app
1199
1200 - Params:
1201   - *optional* `name`
1202   - *optional* `client_id`
1203   - *optional* `page`
1204   - *optional* `page_size`
1205   - *optional* `trusted`
1206
1207 - Response:
1208
1209 ```json
1210 {
1211   "apps": [
1212     {
1213       "id": 1,
1214       "name": "App name",
1215       "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
1216       "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
1217       "redirect_uri": "https://example.com/oauth-callback",
1218       "website": "https://example.com",
1219       "trusted": true
1220     }
1221   ],
1222   "count": 17,
1223   "page_size": 50
1224 }
1225 ```
1226
1227
1228 ## `POST /api/pleroma/admin/oauth_app`
1229
1230 ### Create OAuth App
1231
1232 - Params:
1233   - `name`
1234   - `redirect_uris`
1235   - `scopes`
1236   - *optional* `website`
1237   - *optional* `trusted`
1238
1239 - Response:
1240
1241 ```json
1242 {
1243   "id": 1,
1244   "name": "App name",
1245   "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
1246   "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
1247   "redirect_uri": "https://example.com/oauth-callback",
1248   "website": "https://example.com",
1249   "trusted": true
1250 }
1251 ```
1252
1253 - On failure:
1254 ```json
1255 {
1256   "redirect_uris": "can't be blank",
1257   "name": "can't be blank"
1258 }
1259 ```
1260
1261 ## `PATCH /api/pleroma/admin/oauth_app/:id`
1262
1263 ### Update OAuth App
1264
1265 - Params:
1266   -  *optional* `name`
1267   -  *optional* `redirect_uris`
1268   -  *optional* `scopes`
1269   -  *optional* `website`
1270   -  *optional* `trusted`
1271
1272 - Response:
1273
1274 ```json
1275 {
1276   "id": 1,
1277   "name": "App name",
1278   "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk",
1279   "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY",
1280   "redirect_uri": "https://example.com/oauth-callback",
1281   "website": "https://example.com",
1282   "trusted": true
1283 }
1284 ```
1285
1286 ## `DELETE /api/pleroma/admin/oauth_app/:id`
1287
1288 ### Delete OAuth App
1289
1290 - Params: None
1291
1292 - Response:
1293   - On success: `204`, empty response
1294   - On failure:
1295     - 400 Bad Request `"Invalid parameters"` when `status` is missing
1296
1297 ## `GET /api/pleroma/admin/media_proxy_caches`
1298
1299 ### Get a list of all banned MediaProxy URLs in Cachex
1300
1301 - Authentication: required
1302 - Params:
1303 - *optional* `page`: **integer** page number
1304 - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
1305 - *optional* `query`: **string** search term
1306
1307 - Response:
1308
1309 ``` json
1310 {
1311   "page_size": integer,
1312   "count": integer,
1313   "urls": [
1314     "http://example.com/media/a688346.jpg",
1315     "http://example.com/media/fb1f4d.jpg"
1316   ]
1317 }
1318
1319 ```
1320
1321 ## `POST /api/pleroma/admin/media_proxy_caches/delete`
1322
1323 ### Remove a banned MediaProxy URL from Cachex
1324
1325 - Authentication: required
1326 - Params:
1327   - `urls` (array)
1328
1329 - Response:
1330
1331 ``` json
1332 { }
1333
1334 ```
1335
1336 ## `POST /api/pleroma/admin/media_proxy_caches/purge`
1337
1338 ### Purge a MediaProxy URL
1339
1340 - Authentication: required
1341 - Params:
1342   - `urls` (array)
1343   - `ban` (boolean)
1344
1345 - Response:
1346
1347 ``` json
1348 { }
1349
1350 ```
1351
1352 ## GET /api/pleroma/admin/users/:nickname/chats
1353
1354 ### List a user's chats
1355
1356 - Params: None
1357
1358 - Response:
1359
1360 ```json
1361 [
1362    {
1363       "sender": {
1364         "id": "someflakeid",
1365         "username": "somenick",
1366         ...
1367       },
1368       "receiver": {
1369         "id": "someflakeid",
1370         "username": "somenick",
1371         ...
1372       },
1373       "id" : "1",
1374       "unread" : 2,
1375       "last_message" : {...}, // The last message in that chat
1376       "updated_at": "2020-04-21T15:11:46.000Z"
1377    }
1378 ]
1379 ```
1380
1381 ## GET /api/pleroma/admin/chats/:chat_id
1382
1383 ### View a single chat
1384
1385 - Params: None
1386
1387 - Response:
1388
1389 ```json
1390 {
1391   "sender": {
1392     "id": "someflakeid",
1393     "username": "somenick",
1394     ...
1395   },
1396   "receiver": {
1397     "id": "someflakeid",
1398     "username": "somenick",
1399     ...
1400   },
1401   "id" : "1",
1402   "unread" : 2,
1403   "last_message" : {...}, // The last message in that chat
1404   "updated_at": "2020-04-21T15:11:46.000Z"
1405 }
1406 ```
1407
1408 ## GET /api/pleroma/admin/chats/:chat_id/messages
1409
1410 ### List the messages in a chat
1411
1412 - Params: `max_id`, `min_id`
1413
1414 - Response:
1415
1416 ```json
1417 [
1418   {
1419     "account_id": "someflakeid",
1420     "chat_id": "1",
1421     "content": "Check this out :firefox:",
1422     "created_at": "2020-04-21T15:11:46.000Z",
1423     "emojis": [
1424       {
1425         "shortcode": "firefox",
1426         "static_url": "https://dontbulling.me/emoji/Firefox.gif",
1427         "url": "https://dontbulling.me/emoji/Firefox.gif",
1428         "visible_in_picker": false
1429       }
1430     ],
1431     "id": "13",
1432     "unread": true
1433   },
1434   {
1435     "account_id": "someflakeid",
1436     "chat_id": "1",
1437     "content": "Whats' up?",
1438     "created_at": "2020-04-21T15:06:45.000Z",
1439     "emojis": [],
1440     "id": "12",
1441     "unread": false
1442   }
1443 ]
1444 ```
1445
1446 ## DELETE /api/pleroma/admin/chats/:chat_id/messages/:message_id
1447
1448 ### Delete a single message
1449
1450 - Params: None
1451
1452 - Response:
1453
1454 ```json
1455 {
1456   "account_id": "someflakeid",
1457   "chat_id": "1",
1458   "content": "Check this out :firefox:",
1459   "created_at": "2020-04-21T15:11:46.000Z",
1460   "emojis": [
1461     {
1462       "shortcode": "firefox",
1463       "static_url": "https://dontbulling.me/emoji/Firefox.gif",
1464       "url": "https://dontbulling.me/emoji/Firefox.gif",
1465       "visible_in_picker": false
1466     }
1467   ],
1468   "id": "13",
1469   "unread": false
1470 }
1471 ```
1472
1473 ## `GET /api/pleroma/admin/instance_document/:document_name`
1474
1475 ### Get an instance document
1476
1477 - Authentication: required
1478
1479 - Response:
1480
1481 Returns the content of the document
1482
1483 ```html
1484 <h1>Instance panel</h1>
1485 ```
1486
1487 ## `PATCH /api/pleroma/admin/instance_document/:document_name`
1488 - Params:
1489   - `file` (the file to be uploaded, using multipart form data.)
1490
1491 ### Update an instance document
1492
1493 - Authentication: required
1494
1495 - Response:
1496
1497 ``` json
1498 {
1499   "url": "https://example.com/instance/panel.html"
1500 }
1501 ```
1502
1503 ## `DELETE /api/pleroma/admin/instance_document/:document_name`
1504
1505 ### Delete an instance document
1506
1507 - Response:
1508
1509 ``` json
1510 {
1511   "url": "https://example.com/instance/panel.html"
1512 }
1513 ```
1514
1515 ## `GET /api/pleroma/admin/frontends
1516
1517 ### List available frontends
1518
1519 - Response:
1520
1521 ```json
1522 [
1523    {
1524     "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
1525     "git": "https://git.pleroma.social/pleroma/fedi-fe",
1526     "installed": true,
1527     "name": "fedi-fe",
1528     "ref": "master"
1529   },
1530   {
1531     "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
1532     "git": "https://git.pleroma.social/lambadalambda/kenoma",
1533     "installed": false,
1534     "name": "kenoma",
1535     "ref": "master"
1536   }
1537 ]
1538 ```
1539
1540 ## `POST /api/pleroma/admin/frontends/install`
1541
1542 ### Install a frontend
1543
1544 - Params:
1545   - `name`: frontend name, required
1546   - `ref`: frontend ref
1547   - `file`: path to a frontend zip file
1548   - `build_url`: build URL
1549   - `build_dir`: build directory
1550
1551 - Response:
1552
1553 ```json
1554 [
1555    {
1556     "build_url": "https://git.pleroma.social/pleroma/fedi-fe/-/jobs/artifacts/${ref}/download?job=build",
1557     "git": "https://git.pleroma.social/pleroma/fedi-fe",
1558     "installed": true,
1559     "name": "fedi-fe",
1560     "ref": "master"
1561   },
1562   {
1563     "build_url": "https://git.pleroma.social/lambadalambda/kenoma/-/jobs/artifacts/${ref}/download?job=build",
1564     "git": "https://git.pleroma.social/lambadalambda/kenoma",
1565     "installed": false,
1566     "name": "kenoma",
1567     "ref": "master"
1568   }
1569 ]
1570 ```
1571
1572 ```json
1573 {
1574   "error": "Could not install frontend"
1575 }
1576 ```