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