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
  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   - *optional* `page`: **integer** page number
  18   - *optional* `page_size`: **integer** number of users per page (default is `50`)
  19 - Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10`
  20 - Response:
  21
  22 ```JSON
  23 {
  24   "page_size": integer,
  25   "count": integer,
  26   "users": [
  27     {
  28       "deactivated": bool,
  29       "id": integer,
  30       "nickname": string,
  31       "roles": {
  32         "admin": bool,
  33         "moderator": bool
  34       },
  35       "local": bool,
  36       "tags": array
  37     },
  38     ...
  39   ]
  40 }
  41 ```
  42
  43 ## `/api/pleroma/admin/user`
  44
  45 ### Remove a user
  46
  47 - Method `DELETE`
  48 - Params:
  49   - `nickname`
  50 - Response: User’s nickname
  51
  52 ### Create a user
  53
  54 - Method: `POST`
  55 - Params:
  56   - `nickname`
  57   - `email`
  58   - `password`
  59 - Response: User’s nickname
  60
  61 ## `/api/pleroma/admin/user/follow`
  62 ### Make a user follow another user
  63
  64 - Methods: `POST`
  65 - Params:
  66  - `follower`: The nickname of the follower
  67  - `followed`: The nickname of the followed
  68 - Response:
  69  - "ok"
  70
  71 ## `/api/pleroma/admin/user/unfollow`
  72 ### Make a user unfollow another user
  73
  74 - Methods: `POST`
  75 - Params:
  76  - `follower`: The nickname of the follower
  77  - `followed`: The nickname of the followed
  78 - Response:
  79  - "ok"
  80
  81 ## `/api/pleroma/admin/users/:nickname/toggle_activation`
  82
  83 ### Toggle user activation
  84
  85 - Method: `PATCH`
  86 - Params:
  87   - `nickname`
  88 - Response: User’s object
  89
  90 ```JSON
  91 {
  92   "deactivated": bool,
  93   "id": integer,
  94   "nickname": string
  95 }
  96 ```
  97
  98 ## `/api/pleroma/admin/users/tag`
  99
 100 ### Tag a list of users
 101
 102 - Method: `PUT`
 103 - Params:
 104   - `nickname`
 105   - `tags`
 106
 107 ### Untag a list of users
 108
 109 - Method: `DELETE`
 110 - Params:
 111   - `nickname`
 112   - `tags`
 113
 114 ## `/api/pleroma/admin/permission_group/:nickname`
 115
 116 ### Get user user permission groups membership
 117
 118 - Method: `GET`
 119 - Params: none
 120 - Response:
 121
 122 ```JSON
 123 {
 124   "is_moderator": bool,
 125   "is_admin": bool
 126 }
 127 ```
 128
 129 ## `/api/pleroma/admin/permission_group/:nickname/:permission_group`
 130
 131 Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
 132
 133 ### Get user user permission groups membership per permission group
 134
 135 - Method: `GET`
 136 - Params: none
 137 - Response:
 138
 139 ```JSON
 140 {
 141   "is_moderator": bool,
 142   "is_admin": bool
 143 }
 144 ```
 145
 146 ### Add user in permission group
 147
 148 - Method: `POST`
 149 - Params: none
 150 - Response:
 151   - On failure: `{"error": "…"}`
 152   - On success: JSON of the `user.info`
 153
 154 ### Remove user from permission group
 155
 156 - Method: `DELETE`
 157 - Params: none
 158 - Response:
 159   - On failure: `{"error": "…"}`
 160   - On success: JSON of the `user.info`
 161 - Note: An admin cannot revoke their own admin status.
 162
 163 ## `/api/pleroma/admin/activation_status/:nickname`
 164
 165 ### Active or deactivate a user
 166
 167 - Method: `PUT`
 168 - Params:
 169   - `nickname`
 170   - `status` BOOLEAN field, false value means deactivation.
 171
 172 ## `/api/pleroma/admin/users/:nickname`
 173
 174 ### Retrive the details of a user
 175
 176 - Method: `GET`
 177 - Params:
 178   - `nickname`
 179 - Response:
 180   - On failure: `Not found`
 181   - On success: JSON of the user
 182
 183 ## `/api/pleroma/admin/relay`
 184
 185 ### Follow a Relay
 186
 187 - Methods: `POST`
 188 - Params:
 189   - `relay_url`
 190 - Response:
 191   - On success: URL of the followed relay
 192
 193 ### Unfollow a Relay
 194
 195 - Methods: `DELETE`
 196 - Params:
 197   - `relay_url`
 198 - Response:
 199   - On success: URL of the unfollowed relay
 200
 201 ## `/api/pleroma/admin/invite_token`
 202
 203 ### Get an account registration invite token
 204
 205 - Methods: `GET`
 206 - Params:
 207   - *optional* `invite` => [
 208     - *optional* `max_use` (integer)
 209     - *optional* `expires_at` (date string e.g. "2019-04-07")
 210   ]
 211 - Response: invite token (base64 string)
 212
 213 ## `/api/pleroma/admin/invites`
 214
 215 ### Get a list of generated invites
 216
 217 - Methods: `GET`
 218 - Params: none
 219 - Response:
 220
 221 ```JSON
 222 {
 223
 224   "invites": [
 225     {
 226       "id": integer,
 227       "token": string,
 228       "used": boolean,
 229       "expires_at": date,
 230       "uses": integer,
 231       "max_use": integer,
 232       "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 233     },
 234     ...
 235   ]
 236 }
 237 ```
 238
 239 ## `/api/pleroma/admin/revoke_invite`
 240
 241 ### Revoke invite by token
 242
 243 - Methods: `POST`
 244 - Params:
 245   - `token`
 246 - Response:
 247
 248 ```JSON
 249 {
 250   "id": integer,
 251   "token": string,
 252   "used": boolean,
 253   "expires_at": date,
 254   "uses": integer,
 255   "max_use": integer,
 256   "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`)
 257
 258 }
 259 ```
 260
 261
 262 ## `/api/pleroma/admin/email_invite`
 263
 264 ### Sends registration invite via email
 265
 266 - Methods: `POST`
 267 - Params:
 268   - `email`
 269   - `name`, optional
 270
 271 ## `/api/pleroma/admin/password_reset`
 272
 273 ### Get a password reset token for a given nickname
 274
 275 - Methods: `GET`
 276 - Params: none
 277 - Response: password reset token (base64 string)