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