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