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