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 ## `/api/pleroma/admin/users`
   6
   7 ### List users
   8
   9 - Method `GET`
  10 - Query Params:
  11   - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
  12   - *optional* `filters`: **string** comma-separated string of filters:
  13     - `local`: only local users
  14     - `external`: only external users
  15     - `active`: only active users
  16     - `deactivated`: only deactivated users
  17     - `is_admin`: users with admin role
  18     - `is_moderator`: users with moderator role
  19   - *optional* `page`: **integer** page number
  20   - *optional* `page_size`: **integer** number of users per page (default is `50`)
  21   - *optional* `tags`: **[string]** tags list
  22   - *optional* `name`: **string** user display name
  23   - *optional* `email`: **string** user email
  24 - Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com`
  25 - Response:
  26
  27 ```json
  28 {
  29   "page_size": integer,
  30   "count": integer,
  31   "users": [
  32     {
  33       "deactivated": bool,
  34       "id": integer,
  35       "nickname": string,
  36       "roles": {
  37         "admin": bool,
  38         "moderator": bool
  39       },
  40       "local": bool,
  41       "tags": array,
  42       "avatar": string,
  43       "display_name": string
  44     },
  45     ...
  46   ]
  47 }
  48 ```
  49
  50 ## `/api/pleroma/admin/users`
  51
  52 ### Remove a user
  53
  54 - Method `DELETE`
  55 - Params:
  56   - `nickname`
  57 - Response: User’s nickname
  58
  59 ### Create a user
  60
  61 - Method: `POST`
  62 - Params:
  63   `users`: [
  64     {
  65       `nickname`,
  66       `email`,
  67       `password`
  68     }
  69   ]
  70 - Response: User’s nickname
  71
  72 ## `/api/pleroma/admin/users/follow`
  73 ### Make a user follow another user
  74
  75 - Methods: `POST`
  76 - Params:
  77  - `follower`: The nickname of the follower
  78  - `followed`: The nickname of the followed
  79 - Response:
  80  - "ok"
  81
  82 ## `/api/pleroma/admin/users/unfollow`
  83 ### Make a user unfollow another user
  84
  85 - Methods: `POST`
  86 - Params:
  87  - `follower`: The nickname of the follower
  88  - `followed`: The nickname of the followed
  89 - Response:
  90  - "ok"
  91
  92 ## `/api/pleroma/admin/users/:nickname/toggle_activation`
  93
  94 ### Toggle user activation
  95
  96 - Method: `PATCH`
  97 - Params:
  98   - `nickname`
  99 - Response: User’s object
 100
 101 ```json
 102 {
 103   "deactivated": bool,
 104   "id": integer,
 105   "nickname": string
 106 }
 107 ```
 108
 109 ## `/api/pleroma/admin/users/tag`
 110
 111 ### Tag a list of users
 112
 113 - Method: `PUT`
 114 - Params:
 115   - `nicknames` (array)
 116   - `tags` (array)
 117
 118 ### Untag a list of users
 119
 120 - Method: `DELETE`
 121 - Params:
 122   - `nicknames` (array)
 123   - `tags` (array)
 124
 125 ## `/api/pleroma/admin/users/:nickname/permission_group`
 126
 127 ### Get user user permission groups membership
 128
 129 - Method: `GET`
 130 - Params: none
 131 - Response:
 132
 133 ```json
 134 {
 135   "is_moderator": bool,
 136   "is_admin": bool
 137 }
 138 ```
 139
 140 ## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group`
 141
 142 Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
 143
 144 ### Get user user permission groups membership per permission group
 145
 146 - Method: `GET`
 147 - Params: none
 148 - Response:
 149
 150 ```json
 151 {
 152   "is_moderator": bool,
 153   "is_admin": bool
 154 }
 155 ```
 156
 157 ### Add user in permission group
 158
 159 - Method: `POST`
 160 - Params: none
 161 - Response:
 162   - On failure: `{"error": "…"}`
 163   - On success: JSON of the `user.info`
 164
 165 ### Remove user from permission group
 166
 167 - Method: `DELETE`
 168 - Params: none
 169 - Response:
 170   - On failure: `{"error": "…"}`
 171   - On success: JSON of the `user.info`
 172 - Note: An admin cannot revoke their own admin status.
 173
 174 ## `/api/pleroma/admin/users/:nickname/activation_status`
 175
 176 ### Active or deactivate a user
 177
 178 - Method: `PUT`
 179 - Params:
 180   - `nickname`
 181   - `status` BOOLEAN field, false value means deactivation.
 182
 183 ## `/api/pleroma/admin/users/:nickname_or_id`
 184
 185 ### Retrive the details of a user
 186
 187 - Method: `GET`
 188 - Params:
 189   - `nickname` or `id`
 190 - Response:
 191   - On failure: `Not found`
 192   - On success: JSON of the user
 193
 194 ## `/api/pleroma/admin/users/:nickname_or_id/statuses`
 195
 196 ### Retrive user's latest statuses
 197
 198 - Method: `GET`
 199 - Params:
 200   - `nickname` or `id`
 201   - *optional* `page_size`: number of statuses to return (default is `20`)
 202   - *optional* `godmode`: `true`/`false` – allows to see private statuses
 203 - Response:
 204   - On failure: `Not found`
 205   - On success: JSON array of user's latest statuses
 206
 207 ## `/api/pleroma/admin/relay`
 208
 209 ### Follow a Relay
 210
 211 - Methods: `POST`
 212 - Params:
 213   - `relay_url`
 214 - Response:
 215   - On success: URL of the followed relay
 216
 217 ### Unfollow a Relay
 218
 219 - Methods: `DELETE`
 220 - Params:
 221   - `relay_url`
 222 - Response:
 223   - On success: URL of the unfollowed relay
 224
 225 ## `/api/pleroma/admin/users/invite_token`
 226
 227 ### Create an account registration invite token
 228
 229 - Methods: `POST`
 230 - Params:
 231   - *optional* `max_use` (integer)
 232   - *optional* `expires_at` (date string e.g. "2019-04-07")
 233 - Response:
 234
 235 ```json
 236 {
 237   "id": integer,
 238   "token": string,
 239   "used": boolean,
 240   "expires_at": date,
 241   "uses": integer,
 242   "max_use": integer,
 243   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 244 }
 245 ```
 246
 247 ## `/api/pleroma/admin/users/invites`
 248
 249 ### Get a list of generated invites
 250
 251 - Methods: `GET`
 252 - Params: none
 253 - Response:
 254
 255 ```json
 256 {
 257
 258   "invites": [
 259     {
 260       "id": integer,
 261       "token": string,
 262       "used": boolean,
 263       "expires_at": date,
 264       "uses": integer,
 265       "max_use": integer,
 266       "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 267     },
 268     ...
 269   ]
 270 }
 271 ```
 272
 273 ## `/api/pleroma/admin/users/revoke_invite`
 274
 275 ### Revoke invite by token
 276
 277 - Methods: `POST`
 278 - Params:
 279   - `token`
 280 - Response:
 281
 282 ```json
 283 {
 284   "id": integer,
 285   "token": string,
 286   "used": boolean,
 287   "expires_at": date,
 288   "uses": integer,
 289   "max_use": integer,
 290   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 291
 292 }
 293 ```
 294
 295
 296 ## `/api/pleroma/admin/users/email_invite`
 297
 298 ### Sends registration invite via email
 299
 300 - Methods: `POST`
 301 - Params:
 302   - `email`
 303   - `name`, optional
 304
 305 ## `/api/pleroma/admin/users/:nickname/password_reset`
 306
 307 ### Get a password reset token for a given nickname
 308
 309 - Methods: `GET`
 310 - Params: none
 311 - Response:
 312
 313 ```json
 314 {
 315   "token": "base64 reset token",
 316   "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token"
 317 }
 318 ```
 319
 320
 321 ## `/api/pleroma/admin/users/:nickname/force_password_reset`
 322
 323 ### Force passord reset for a user with a given nickname
 324
 325 - Methods: `PATCH`
 326 - Params: none
 327 - Response: none (code `204`)
 328
 329 ## `/api/pleroma/admin/reports`
 330 ### Get a list of reports
 331 - Method `GET`
 332 - Params:
 333   - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
 334   - *optional* `limit`: **integer** the number of records to retrieve
 335   - *optional* `page`: **integer** page number
 336   - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
 337 - Response:
 338   - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
 339   - On success: JSON, returns a list of reports, where:
 340     - `account`: the user who has been reported
 341     - `actor`: the user who has sent the report
 342     - `statuses`: list of statuses that have been included to the report
 343
 344 ```json
 345 {
 346   "total" : 1,
 347   "reports": [
 348     {
 349       "account": {
 350         "acct": "user",
 351         "avatar": "https://pleroma.example.org/images/avi.png",
 352         "avatar_static": "https://pleroma.example.org/images/avi.png",
 353         "bot": false,
 354         "created_at": "2019-04-23T17:32:04.000Z",
 355         "display_name": "User",
 356         "emojis": [],
 357         "fields": [],
 358         "followers_count": 1,
 359         "following_count": 1,
 360         "header": "https://pleroma.example.org/images/banner.png",
 361         "header_static": "https://pleroma.example.org/images/banner.png",
 362         "id": "9i6dAJqSGSKMzLG2Lo",
 363         "locked": false,
 364         "note": "",
 365         "pleroma": {
 366           "confirmation_pending": false,
 367           "hide_favorites": true,
 368           "hide_followers": false,
 369           "hide_follows": false,
 370           "is_admin": false,
 371           "is_moderator": false,
 372           "relationship": {},
 373           "tags": []
 374         },
 375         "source": {
 376           "note": "",
 377           "pleroma": {},
 378           "sensitive": false
 379         },
 380         "tags": ["force_unlisted"],
 381         "statuses_count": 3,
 382         "url": "https://pleroma.example.org/users/user",
 383         "username": "user"
 384       },
 385       "actor": {
 386         "acct": "lain",
 387         "avatar": "https://pleroma.example.org/images/avi.png",
 388         "avatar_static": "https://pleroma.example.org/images/avi.png",
 389         "bot": false,
 390         "created_at": "2019-03-28T17:36:03.000Z",
 391         "display_name": "Roger Braun",
 392         "emojis": [],
 393         "fields": [],
 394         "followers_count": 1,
 395         "following_count": 1,
 396         "header": "https://pleroma.example.org/images/banner.png",
 397         "header_static": "https://pleroma.example.org/images/banner.png",
 398         "id": "9hEkA5JsvAdlSrocam",
 399         "locked": false,
 400         "note": "",
 401         "pleroma": {
 402           "confirmation_pending": false,
 403           "hide_favorites": false,
 404           "hide_followers": false,
 405           "hide_follows": false,
 406           "is_admin": false,
 407           "is_moderator": false,
 408           "relationship": {},
 409           "tags": []
 410         },
 411         "source": {
 412           "note": "",
 413           "pleroma": {},
 414           "sensitive": false
 415         },
 416         "tags": ["force_unlisted"],
 417         "statuses_count": 1,
 418         "url": "https://pleroma.example.org/users/lain",
 419         "username": "lain"
 420       },
 421       "content": "Please delete it",
 422       "created_at": "2019-04-29T19:48:15.000Z",
 423       "id": "9iJGOv1j8hxuw19bcm",
 424       "state": "open",
 425       "statuses": [
 426         {
 427           "account": { ... },
 428           "application": {
 429             "name": "Web",
 430             "website": null
 431           },
 432           "bookmarked": false,
 433           "card": null,
 434           "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>",
 435           "created_at": "2019-04-23T19:15:47.000Z",
 436           "emojis": [],
 437           "favourited": false,
 438           "favourites_count": 0,
 439           "id": "9i6mQ9uVrrOmOime8m",
 440           "in_reply_to_account_id": null,
 441           "in_reply_to_id": null,
 442           "language": null,
 443           "media_attachments": [],
 444           "mentions": [
 445             {
 446               "acct": "lain",
 447               "id": "9hEkA5JsvAdlSrocam",
 448               "url": "https://pleroma.example.org/users/lain",
 449               "username": "lain"
 450             },
 451             {
 452               "acct": "user",
 453               "id": "9i6dAJqSGSKMzLG2Lo",
 454               "url": "https://pleroma.example.org/users/user",
 455               "username": "user"
 456             }
 457           ],
 458           "muted": false,
 459           "pinned": false,
 460           "pleroma": {
 461             "content": {
 462               "text/plain": "@lain click on my link https://www.google.com/"
 463             },
 464             "conversation_id": 28,
 465             "in_reply_to_account_acct": null,
 466             "local": true,
 467             "spoiler_text": {
 468               "text/plain": ""
 469             }
 470           },
 471           "reblog": null,
 472           "reblogged": false,
 473           "reblogs_count": 0,
 474           "replies_count": 0,
 475           "sensitive": false,
 476           "spoiler_text": "",
 477           "tags": [],
 478           "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
 479           "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
 480           "visibility": "direct"
 481         }
 482       ]
 483     }
 484   ]
 485 }
 486 ```
 487
 488 ## `/api/pleroma/admin/reports/:id`
 489 ### Get an individual report
 490 - Method `GET`
 491 - Params:
 492   - `id`
 493 - Response:
 494   - On failure:
 495     - 403 Forbidden `{"error": "error_msg"}`
 496     - 404 Not Found `"Not found"`
 497   - On success: JSON, Report object (see above)
 498
 499 ## `/api/pleroma/admin/reports/:id`
 500 ### Change the state of the report
 501 - Method `PUT`
 502 - Params:
 503   - `id`
 504   - `state`: required, the new state. Valid values are `open`, `closed` and `resolved`
 505 - Response:
 506   - On failure:
 507     - 400 Bad Request `"Unsupported state"`
 508     - 403 Forbidden `{"error": "error_msg"}`
 509     - 404 Not Found `"Not found"`
 510   - On success: JSON, Report object (see above)
 511
 512 ## `/api/pleroma/admin/reports/:id/respond`
 513 ### Respond to a report
 514 - Method `POST`
 515 - Params:
 516   - `id`
 517   - `status`: required, the message
 518 - Response:
 519   - On failure:
 520     - 400 Bad Request `"Invalid parameters"` when `status` is missing
 521     - 403 Forbidden `{"error": "error_msg"}`
 522     - 404 Not Found `"Not found"`
 523   - On success: JSON, created Mastodon Status entity
 524
 525 ```json
 526 {
 527   "account": { ... },
 528   "application": {
 529     "name": "Web",
 530     "website": null
 531   },
 532   "bookmarked": false,
 533   "card": null,
 534   "content": "Your claim is going to be closed",
 535   "created_at": "2019-05-11T17:13:03.000Z",
 536   "emojis": [],
 537   "favourited": false,
 538   "favourites_count": 0,
 539   "id": "9ihuiSL1405I65TmEq",
 540   "in_reply_to_account_id": null,
 541   "in_reply_to_id": null,
 542   "language": null,
 543   "media_attachments": [],
 544   "mentions": [
 545     {
 546       "acct": "user",
 547       "id": "9i6dAJqSGSKMzLG2Lo",
 548       "url": "https://pleroma.example.org/users/user",
 549       "username": "user"
 550     },
 551     {
 552       "acct": "admin",
 553       "id": "9hEkA5JsvAdlSrocam",
 554       "url": "https://pleroma.example.org/users/admin",
 555       "username": "admin"
 556     }
 557   ],
 558   "muted": false,
 559   "pinned": false,
 560   "pleroma": {
 561     "content": {
 562       "text/plain": "Your claim is going to be closed"
 563     },
 564     "conversation_id": 35,
 565     "in_reply_to_account_acct": null,
 566     "local": true,
 567     "spoiler_text": {
 568       "text/plain": ""
 569     }
 570   },
 571   "reblog": null,
 572   "reblogged": false,
 573   "reblogs_count": 0,
 574   "replies_count": 0,
 575   "sensitive": false,
 576   "spoiler_text": "",
 577   "tags": [],
 578   "uri": "https://pleroma.example.org/objects/cab0836d-9814-46cd-a0ea-529da9db5fcb",
 579   "url": "https://pleroma.example.org/notice/9ihuiSL1405I65TmEq",
 580   "visibility": "direct"
 581 }
 582 ```
 583
 584 ## `/api/pleroma/admin/statuses/:id`
 585 ### Change the scope of an individual reported status
 586 - Method `PUT`
 587 - Params:
 588   - `id`
 589   - `sensitive`: optional, valid values are `true` or `false`
 590   - `visibility`: optional, valid values are `public`, `private` and `unlisted`
 591 - Response:
 592   - On failure:
 593     - 400 Bad Request `"Unsupported visibility"`
 594     - 403 Forbidden `{"error": "error_msg"}`
 595     - 404 Not Found `"Not found"`
 596   - On success: JSON, Mastodon Status entity
 597
 598 ## `/api/pleroma/admin/statuses/:id`
 599 ### Delete an individual reported status
 600 - Method `DELETE`
 601 - Params:
 602   - `id`
 603 - Response:
 604   - On failure:
 605     - 403 Forbidden `{"error": "error_msg"}`
 606     - 404 Not Found `"Not found"`
 607   - On success: 200 OK `{}`
 608
 609
 610 ## `/api/pleroma/admin/config/migrate_to_db`
 611 ### Run mix task pleroma.config migrate_to_db
 612 Copy settings on key `:pleroma` to DB.
 613 - Method `GET`
 614 - Params: none
 615 - Response:
 616
 617 ```json
 618 {}
 619 ```
 620
 621 ## `/api/pleroma/admin/config/migrate_from_db`
 622 ### Run mix task pleroma.config migrate_from_db
 623 Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB.
 624 - Method `GET`
 625 - Params: none
 626 - Response:
 627
 628 ```json
 629 {}
 630 ```
 631
 632 ## `/api/pleroma/admin/config`
 633 ### List config settings
 634 List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
 635 - Method `GET`
 636 - Params: none
 637 - Response:
 638
 639 ```json
 640 {
 641   configs: [
 642     {
 643       "group": string,
 644       "key": string or string with leading `:` for atoms,
 645       "value": string or {} or [] or {"tuple": []}
 646      }
 647   ]
 648 }
 649 ```
 650
 651 ## `/api/pleroma/admin/config`
 652 ### Update config settings
 653 Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
 654 Module name can be passed as string, which starts with `Pleroma`, e.g. `"Pleroma.Upload"`.
 655 Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`.
 656 Tuples can be passed as `{"tuple": ["first_val", Pleroma.Module, []]}`.
 657 `{"tuple": ["some_string", "Pleroma.Some.Module", []]}` will be converted to `{"some_string", Pleroma.Some.Module, []}`.
 658 Keywords can be passed as lists with 2 child tuples, e.g.
 659 `[{"tuple": ["first_val", Pleroma.Module]}, {"tuple": ["second_val", true]}]`.
 660
 661 If value contains list of settings `[subkey: val1, subkey2: val2, subkey3: val3]`, it's possible to remove only subkeys instead of all settings passing `subkeys` parameter. E.g.:
 662 {"group": "pleroma", "key": "some_key", "delete": "true", "subkeys": [":subkey", ":subkey3"]}.
 663
 664 Compile time settings (need instance reboot):
 665 - all settings by this keys:
 666   - `:hackney_pools`
 667   - `:chat`
 668   - `Pleroma.Web.Endpoint`
 669   - `Pleroma.Repo`
 670 - part settings:
 671   - `Pleroma.Captcha` -> `:seconds_valid`
 672   - `Pleroma.Upload` -> `:proxy_remote`
 673   - `:instance` -> `:upload_limit`
 674
 675 - Method `POST`
 676 - Params:
 677   - `configs` => [
 678     - `group` (string)
 679     - `key` (string or string with leading `:` for atoms)
 680     - `value` (string, [], {} or {"tuple": []})
 681     - `delete` = true (optional, if parameter must be deleted)
 682     - `subkeys` [(string with leading `:` for atoms)] (optional, works only if `delete=true` parameter is passed, otherwise will be ignored)
 683   ]
 684
 685 - Request (example):
 686
 687 ```json
 688 {
 689   configs: [
 690     {
 691       "group": "pleroma",
 692       "key": "Pleroma.Upload",
 693       "value": [
 694         {"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
 695         {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]},
 696         {"tuple": [":link_name", true]},
 697         {"tuple": [":proxy_remote", false]},
 698         {"tuple": [":proxy_opts", [
 699           {"tuple": [":redirect_on_failure", false]},
 700           {"tuple": [":max_body_length", 1048576]},
 701           {"tuple": [":http": [
 702             {"tuple": [":follow_redirect", true]},
 703             {"tuple": [":pool", ":upload"]},
 704           ]]}
 705         ]
 706         ]},
 707         {"tuple": [":dispatch", {
 708           "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []]
 709         }]}
 710       ]
 711     }
 712   ]
 713 }
 714 ```
 715
 716 - Response:
 717
 718 ```json
 719 {
 720   configs: [
 721     {
 722       "group": string,
 723       "key": string or string with leading `:` for atoms,
 724       "value": string or {} or [] or {"tuple": []}
 725      }
 726   ]
 727 }
 728 ```
 729
 730 ## `/api/pleroma/admin/moderation_log`
 731 ### Get moderation log
 732 - Method `GET`
 733 - Params:
 734   - *optional* `page`: **integer** page number
 735   - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
 736   - *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`
 737   - *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
 738   - *optional* `user_id`: **integer** filter logs by actor's id
 739   - *optional* `search`: **string** search logs by the log message
 740 - Response:
 741
 742 ```json
 743 [
 744   {
 745     "data": {
 746       "actor": {
 747         "id": 1,
 748         "nickname": "lain"
 749       },
 750       "action": "relay_follow"
 751     },
 752     "time": 1502812026, // timestamp
 753     "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
 754   }
 755 ]
 756 ```
 757
 758 ## `POST /api/pleroma/admin/reload_emoji`
 759 ### Reload the instance's custom emoji
 760 * Method `POST`
 761 * Authentication: required
 762 * Params: None
 763 * Response: JSON, "ok" and 200 status