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/users/:nickname_or_id/statuses`
 191
 192 ### Retrive user's latest statuses
 193
 194 - Method: `GET`
 195 - Params:
 196   - `nickname` or `id`
 197   - *optional* `page_size`: number of statuses to return (default is `20`)
 198   - *optional* `godmode`: `true`/`false` – allows to see private statuses
 199 - Response:
 200   - On failure: `Not found`
 201   - On success: JSON array of user's latest statuses
 202
 203 ## `/api/pleroma/admin/relay`
 204
 205 ### Follow a Relay
 206
 207 - Methods: `POST`
 208 - Params:
 209   - `relay_url`
 210 - Response:
 211   - On success: URL of the followed relay
 212
 213 ### Unfollow a Relay
 214
 215 - Methods: `DELETE`
 216 - Params:
 217   - `relay_url`
 218 - Response:
 219   - On success: URL of the unfollowed relay
 220
 221 ## `/api/pleroma/admin/users/invite_token`
 222
 223 ### Get an account registration invite token
 224
 225 - Methods: `GET`
 226 - Params:
 227   - *optional* `invite` => [
 228     - *optional* `max_use` (integer)
 229     - *optional* `expires_at` (date string e.g. "2019-04-07")
 230   ]
 231 - Response: invite token (base64 string)
 232
 233 ## `/api/pleroma/admin/users/invites`
 234
 235 ### Get a list of generated invites
 236
 237 - Methods: `GET`
 238 - Params: none
 239 - Response:
 240
 241 ```json
 242 {
 243
 244   "invites": [
 245     {
 246       "id": integer,
 247       "token": string,
 248       "used": boolean,
 249       "expires_at": date,
 250       "uses": integer,
 251       "max_use": integer,
 252       "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 253     },
 254     ...
 255   ]
 256 }
 257 ```
 258
 259 ## `/api/pleroma/admin/users/revoke_invite`
 260
 261 ### Revoke invite by token
 262
 263 - Methods: `POST`
 264 - Params:
 265   - `token`
 266 - Response:
 267
 268 ```json
 269 {
 270   "id": integer,
 271   "token": string,
 272   "used": boolean,
 273   "expires_at": date,
 274   "uses": integer,
 275   "max_use": integer,
 276   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 277
 278 }
 279 ```
 280
 281
 282 ## `/api/pleroma/admin/users/email_invite`
 283
 284 ### Sends registration invite via email
 285
 286 - Methods: `POST`
 287 - Params:
 288   - `email`
 289   - `name`, optional
 290
 291 ## `/api/pleroma/admin/users/:nickname/password_reset`
 292
 293 ### Get a password reset token for a given nickname
 294
 295 - Methods: `GET`
 296 - Params: none
 297 - Response: password reset token (base64 string)
 298
 299 ## `/api/pleroma/admin/reports`
 300 ### Get a list of reports
 301 - Method `GET`
 302 - Params:
 303   - `state`: optional, the state of reports. Valid values are `open`, `closed` and `resolved`
 304   - `limit`: optional, the number of records to retrieve
 305   - `since_id`: optional, returns results that are more recent than the specified id
 306   - `max_id`: optional, returns results that are older than the specified id
 307 - Response:
 308   - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin
 309   - On success: JSON, returns a list of reports, where:
 310     - `account`: the user who has been reported
 311     - `actor`: the user who has sent the report
 312     - `statuses`: list of statuses that have been included to the report
 313
 314 ```json
 315 {
 316   "total" : 1,
 317   "reports": [
 318     {
 319       "account": {
 320         "acct": "user",
 321         "avatar": "https://pleroma.example.org/images/avi.png",
 322         "avatar_static": "https://pleroma.example.org/images/avi.png",
 323         "bot": false,
 324         "created_at": "2019-04-23T17:32:04.000Z",
 325         "display_name": "User",
 326         "emojis": [],
 327         "fields": [],
 328         "followers_count": 1,
 329         "following_count": 1,
 330         "header": "https://pleroma.example.org/images/banner.png",
 331         "header_static": "https://pleroma.example.org/images/banner.png",
 332         "id": "9i6dAJqSGSKMzLG2Lo",
 333         "locked": false,
 334         "note": "",
 335         "pleroma": {
 336           "confirmation_pending": false,
 337           "hide_favorites": true,
 338           "hide_followers": false,
 339           "hide_follows": false,
 340           "is_admin": false,
 341           "is_moderator": false,
 342           "relationship": {},
 343           "tags": []
 344         },
 345         "source": {
 346           "note": "",
 347           "pleroma": {},
 348           "sensitive": false
 349         },
 350         "tags": ["force_unlisted"],
 351         "statuses_count": 3,
 352         "url": "https://pleroma.example.org/users/user",
 353         "username": "user"
 354       },
 355       "actor": {
 356         "acct": "lain",
 357         "avatar": "https://pleroma.example.org/images/avi.png",
 358         "avatar_static": "https://pleroma.example.org/images/avi.png",
 359         "bot": false,
 360         "created_at": "2019-03-28T17:36:03.000Z",
 361         "display_name": "Roger Braun",
 362         "emojis": [],
 363         "fields": [],
 364         "followers_count": 1,
 365         "following_count": 1,
 366         "header": "https://pleroma.example.org/images/banner.png",
 367         "header_static": "https://pleroma.example.org/images/banner.png",
 368         "id": "9hEkA5JsvAdlSrocam",
 369         "locked": false,
 370         "note": "",
 371         "pleroma": {
 372           "confirmation_pending": false,
 373           "hide_favorites": false,
 374           "hide_followers": false,
 375           "hide_follows": false,
 376           "is_admin": false,
 377           "is_moderator": false,
 378           "relationship": {},
 379           "tags": []
 380         },
 381         "source": {
 382           "note": "",
 383           "pleroma": {},
 384           "sensitive": false
 385         },
 386         "tags": ["force_unlisted"],
 387         "statuses_count": 1,
 388         "url": "https://pleroma.example.org/users/lain",
 389         "username": "lain"
 390       },
 391       "content": "Please delete it",
 392       "created_at": "2019-04-29T19:48:15.000Z",
 393       "id": "9iJGOv1j8hxuw19bcm",
 394       "state": "open",
 395       "statuses": [
 396         {
 397           "account": { ... },
 398           "application": {
 399             "name": "Web",
 400             "website": null
 401           },
 402           "bookmarked": false,
 403           "card": null,
 404           "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>",
 405           "created_at": "2019-04-23T19:15:47.000Z",
 406           "emojis": [],
 407           "favourited": false,
 408           "favourites_count": 0,
 409           "id": "9i6mQ9uVrrOmOime8m",
 410           "in_reply_to_account_id": null,
 411           "in_reply_to_id": null,
 412           "language": null,
 413           "media_attachments": [],
 414           "mentions": [
 415             {
 416               "acct": "lain",
 417               "id": "9hEkA5JsvAdlSrocam",
 418               "url": "https://pleroma.example.org/users/lain",
 419               "username": "lain"
 420             },
 421             {
 422               "acct": "user",
 423               "id": "9i6dAJqSGSKMzLG2Lo",
 424               "url": "https://pleroma.example.org/users/user",
 425               "username": "user"
 426             }
 427           ],
 428           "muted": false,
 429           "pinned": false,
 430           "pleroma": {
 431             "content": {
 432               "text/plain": "@lain click on my link https://www.google.com/"
 433             },
 434             "conversation_id": 28,
 435             "in_reply_to_account_acct": null,
 436             "local": true,
 437             "spoiler_text": {
 438               "text/plain": ""
 439             }
 440           },
 441           "reblog": null,
 442           "reblogged": false,
 443           "reblogs_count": 0,
 444           "replies_count": 0,
 445           "sensitive": false,
 446           "spoiler_text": "",
 447           "tags": [],
 448           "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396",
 449           "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m",
 450           "visibility": "direct"
 451         }
 452       ]
 453     }
 454   ]
 455 }
 456 ```
 457
 458 ## `/api/pleroma/admin/reports/:id`
 459 ### Get an individual report
 460 - Method `GET`
 461 - Params:
 462   - `id`
 463 - Response:
 464   - On failure:
 465     - 403 Forbidden `{"error": "error_msg"}`
 466     - 404 Not Found `"Not found"`
 467   - On success: JSON, Report object (see above)
 468
 469 ## `/api/pleroma/admin/reports/:id`
 470 ### Change the state of the report
 471 - Method `PUT`
 472 - Params:
 473   - `id`
 474   - `state`: required, the new state. Valid values are `open`, `closed` and `resolved`
 475 - Response:
 476   - On failure:
 477     - 400 Bad Request `"Unsupported state"`
 478     - 403 Forbidden `{"error": "error_msg"}`
 479     - 404 Not Found `"Not found"`
 480   - On success: JSON, Report object (see above)
 481
 482 ## `/api/pleroma/admin/reports/:id/respond`
 483 ### Respond to a report
 484 - Method `POST`
 485 - Params:
 486   - `id`
 487   - `status`: required, the message
 488 - Response:
 489   - On failure:
 490     - 400 Bad Request `"Invalid parameters"` when `status` is missing
 491     - 403 Forbidden `{"error": "error_msg"}`
 492     - 404 Not Found `"Not found"`
 493   - On success: JSON, created Mastodon Status entity
 494
 495 ```json
 496 {
 497   "account": { ... },
 498   "application": {
 499     "name": "Web",
 500     "website": null
 501   },
 502   "bookmarked": false,
 503   "card": null,
 504   "content": "Your claim is going to be closed",
 505   "created_at": "2019-05-11T17:13:03.000Z",
 506   "emojis": [],
 507   "favourited": false,
 508   "favourites_count": 0,
 509   "id": "9ihuiSL1405I65TmEq",
 510   "in_reply_to_account_id": null,
 511   "in_reply_to_id": null,
 512   "language": null,
 513   "media_attachments": [],
 514   "mentions": [
 515     {
 516       "acct": "user",
 517       "id": "9i6dAJqSGSKMzLG2Lo",
 518       "url": "https://pleroma.example.org/users/user",
 519       "username": "user"
 520     },
 521     {
 522       "acct": "admin",
 523       "id": "9hEkA5JsvAdlSrocam",
 524       "url": "https://pleroma.example.org/users/admin",
 525       "username": "admin"
 526     }
 527   ],
 528   "muted": false,
 529   "pinned": false,
 530   "pleroma": {
 531     "content": {
 532       "text/plain": "Your claim is going to be closed"
 533     },
 534     "conversation_id": 35,
 535     "in_reply_to_account_acct": null,
 536     "local": true,
 537     "spoiler_text": {
 538       "text/plain": ""
 539     }
 540   },
 541   "reblog": null,
 542   "reblogged": false,
 543   "reblogs_count": 0,
 544   "replies_count": 0,
 545   "sensitive": false,
 546   "spoiler_text": "",
 547   "tags": [],
 548   "uri": "https://pleroma.example.org/objects/cab0836d-9814-46cd-a0ea-529da9db5fcb",
 549   "url": "https://pleroma.example.org/notice/9ihuiSL1405I65TmEq",
 550   "visibility": "direct"
 551 }
 552 ```
 553
 554 ## `/api/pleroma/admin/statuses/:id`
 555 ### Change the scope of an individual reported status
 556 - Method `PUT`
 557 - Params:
 558   - `id`
 559   - `sensitive`: optional, valid values are `true` or `false`
 560   - `visibility`: optional, valid values are `public`, `private` and `unlisted`
 561 - Response:
 562   - On failure:
 563     - 400 Bad Request `"Unsupported visibility"`
 564     - 403 Forbidden `{"error": "error_msg"}`
 565     - 404 Not Found `"Not found"`
 566   - On success: JSON, Mastodon Status entity
 567
 568 ## `/api/pleroma/admin/statuses/:id`
 569 ### Delete an individual reported status
 570 - Method `DELETE`
 571 - Params:
 572   - `id`
 573 - Response:
 574   - On failure:
 575     - 403 Forbidden `{"error": "error_msg"}`
 576     - 404 Not Found `"Not found"`
 577   - On success: 200 OK `{}`
 578
 579
 580 ## `/api/pleroma/admin/config/migrate_to_db`
 581 ### Run mix task pleroma.config migrate_to_db
 582 Copy settings on key `:pleroma` to DB.
 583 - Method `GET`
 584 - Params: none
 585 - Response:
 586
 587 ```json
 588 {}
 589 ```
 590
 591 ## `/api/pleroma/admin/config/migrate_from_db`
 592 ### Run mix task pleroma.config migrate_from_db
 593 Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB.
 594 - Method `GET`
 595 - Params: none
 596 - Response:
 597
 598 ```json
 599 {}
 600 ```
 601
 602 ## `/api/pleroma/admin/config`
 603 ### List config settings
 604 List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
 605 - Method `GET`
 606 - Params: none
 607 - Response:
 608
 609 ```json
 610 {
 611   configs: [
 612     {
 613       "group": string,
 614       "key": string or string with leading `:` for atoms,
 615       "value": string or {} or [] or {"tuple": []}
 616      }
 617   ]
 618 }
 619 ```
 620
 621 ## `/api/pleroma/admin/config`
 622 ### Update config settings
 623 Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
 624 Module name can be passed as string, which starts with `Pleroma`, e.g. `"Pleroma.Upload"`.
 625 Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`.
 626 Tuples can be passed as `{"tuple": ["first_val", Pleroma.Module, []]}`.
 627 `{"tuple": ["some_string", "Pleroma.Some.Module", []]}` will be converted to `{"some_string", Pleroma.Some.Module, []}`.
 628 Keywords can be passed as lists with 2 child tuples, e.g.
 629 `[{"tuple": ["first_val", Pleroma.Module]}, {"tuple": ["second_val", true]}]`.
 630
 631 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.:
 632 {"group": "pleroma", "key": "some_key", "delete": "true", "subkeys": [":subkey", ":subkey3"]}.
 633
 634 Compile time settings (need instance reboot):
 635 - all settings by this keys:
 636   - `:hackney_pools`
 637   - `:chat`
 638   - `Pleroma.Web.Endpoint`
 639   - `Pleroma.Repo`
 640 - part settings:
 641   - `Pleroma.Captcha` -> `:seconds_valid`
 642   - `Pleroma.Upload` -> `:proxy_remote`
 643   - `:instance` -> `:upload_limit`
 644
 645 - Method `POST`
 646 - Params:
 647   - `configs` => [
 648     - `group` (string)
 649     - `key` (string or string with leading `:` for atoms)
 650     - `value` (string, [], {} or {"tuple": []})
 651     - `delete` = true (optional, if parameter must be deleted)
 652     - `subkeys` [(string with leading `:` for atoms)] (optional, works only if `delete=true` parameter is passed, otherwise will be ignored)
 653   ]
 654
 655 - Request (example):
 656
 657 ```json
 658 {
 659   configs: [
 660     {
 661       "group": "pleroma",
 662       "key": "Pleroma.Upload",
 663       "value": [
 664         {"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
 665         {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]},
 666         {"tuple": [":link_name", true]},
 667         {"tuple": [":proxy_remote", false]},
 668         {"tuple": [":proxy_opts", [
 669           {"tuple": [":redirect_on_failure", false]},
 670           {"tuple": [":max_body_length", 1048576]},
 671           {"tuple": [":http": [
 672             {"tuple": [":follow_redirect", true]},
 673             {"tuple": [":pool", ":upload"]},
 674           ]]}
 675         ]
 676         ]},
 677         {"tuple": [":dispatch", {
 678           "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []]
 679         }]}
 680       ]
 681     }
 682   ]
 683 }
 684
 685 - Response:
 686
 687 ```json
 688 {
 689   configs: [
 690     {
 691       "group": string,
 692       "key": string or string with leading `:` for atoms,
 693       "value": string or {} or [] or {"tuple": []}
 694      }
 695   ]
 696 }
 697 ```
 698
 699 ## `/api/pleroma/admin/moderation_log`
 700 ### Get moderation log
 701 - Method `GET`
 702 - Params:
 703   - *optional* `page`: **integer** page number
 704   - *optional* `page_size`: **integer** number of users per page (default is `50`)
 705 - Response:
 706
 707 ```json
 708 [
 709   {
 710     "data": {
 711       "actor": {
 712         "id": 1,
 713         "nickname": "lain"
 714       },
 715       "action": "relay_follow"
 716     },
 717     "time": 1502812026, // timestamp
 718     "message": "[2017-08-15 15:47:06] @nick0 followed relay: https://example.org/relay" // log message
 719   }
 720 ]
 721 ```