X-Git-Url: https://git.squeep.com/?a=blobdiff_plain;ds=sidebyside;f=docs%2Fdevelopment%2FAPI%2Fadmin_api.md;h=8f855d251a5ac2b9c2cb945c0534b8699d3f4605;hb=3ec1dbd9223aa44205e90967175f07cc532501ab;hp=04a1814016cf86c03b85bbc2c16064242a82297f;hpb=a853218701c662ce452757a05395c8c6002c5a3d;p=akkoma diff --git a/docs/development/API/admin_api.md b/docs/development/API/admin_api.md index 04a181401..8f855d251 100644 --- a/docs/development/API/admin_api.md +++ b/docs/development/API/admin_api.md @@ -2,14 +2,9 @@ Authentication is required and the user must be an admin. -Configuration options: +The `/api/v1/pleroma/admin/*` path is backwards compatible with `/api/pleroma/admin/*` (`/api/pleroma/admin/*` will be deprecated in the future). -* `[:auth, :enforce_oauth_admin_scope_usage]` â OAuth admin scope requirement toggle. - If `true`, admin actions explicitly demand admin OAuth scope(s) presence in OAuth token (client app must support admin scopes). - If `false` and token doesn't have admin scope(s), `is_admin` user flag grants access to admin-specific actions. - Note that client app needs to explicitly support admin scopes and request them when obtaining auth token. - -## `GET /api/pleroma/admin/users` +## `GET /api/v1/pleroma/admin/users` ### List users @@ -30,7 +25,7 @@ Configuration options: - *optional* `actor_types`: **[string]** actor type list (`Person`, `Service`, `Application`) - *optional* `name`: **string** user display name - *optional* `email`: **string** user email -- 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` +- Example: `https://mypleroma.org/api/v1/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` - Response: ```json @@ -59,7 +54,7 @@ Configuration options: } ``` -## DEPRECATED `DELETE /api/pleroma/admin/users` +## DEPRECATED `DELETE /api/v1/pleroma/admin/users` ### Remove a user @@ -67,7 +62,7 @@ Configuration options: - `nickname` - Response: Userâs nickname -## `DELETE /api/pleroma/admin/users` +## `DELETE /api/v1/pleroma/admin/users` ### Remove a user @@ -88,7 +83,7 @@ Configuration options: ] - Response: Userâs nickname -## `POST /api/pleroma/admin/users/follow` +## `POST /api/v1/pleroma/admin/users/follow` ### Make a user follow another user @@ -98,7 +93,7 @@ Configuration options: - Response: - "ok" -## `POST /api/pleroma/admin/users/unfollow` +## `POST /api/v1/pleroma/admin/users/unfollow` ### Make a user unfollow another user @@ -108,7 +103,7 @@ Configuration options: - Response: - "ok" -## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation` +## `PATCH /api/v1/pleroma/admin/users/:nickname/toggle_activation` ### Toggle user activation @@ -124,7 +119,7 @@ Configuration options: } ``` -## `PUT /api/pleroma/admin/users/tag` +## `PUT /api/v1/pleroma/admin/users/tag` ### Tag a list of users @@ -132,7 +127,7 @@ Configuration options: - `nicknames` (array) - `tags` (array) -## `DELETE /api/pleroma/admin/users/tag` +## `DELETE /api/v1/pleroma/admin/users/tag` ### Untag a list of users @@ -140,7 +135,7 @@ Configuration options: - `nicknames` (array) - `tags` (array) -## `GET /api/pleroma/admin/users/:nickname/permission_group` +## `GET /api/v1/pleroma/admin/users/:nickname/permission_group` ### Get user user permission groups membership @@ -154,7 +149,7 @@ Configuration options: } ``` -## `GET /api/pleroma/admin/users/:nickname/permission_group/:permission_group` +## `GET /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group` Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesnât exist. @@ -170,7 +165,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## DEPRECATED `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group` +## DEPRECATED `POST /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group` ### Add user to permission group @@ -179,7 +174,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On failure: `{"error": "â¦"}` - On success: JSON of the user -## `POST /api/pleroma/admin/users/permission_group/:permission_group` +## `POST /api/v1/pleroma/admin/users/permission_group/:permission_group` ### Add users to permission group @@ -189,9 +184,9 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On failure: `{"error": "â¦"}` - On success: JSON of the user -## DEPRECATED `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group` +## DEPRECATED `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group` -## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group` +## `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group` ### Remove user from permission group @@ -201,7 +196,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On success: JSON of the user - Note: An admin cannot revoke their own admin status. -## `DELETE /api/pleroma/admin/users/permission_group/:permission_group` +## `DELETE /api/v1/pleroma/admin/users/permission_group/:permission_group` ### Remove users from permission group @@ -212,7 +207,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On success: JSON of the user - Note: An admin cannot revoke their own admin status. -## `PATCH /api/pleroma/admin/users/activate` +## `PATCH /api/v1/pleroma/admin/users/activate` ### Activate user @@ -230,7 +225,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `PATCH /api/pleroma/admin/users/deactivate` +## `PATCH /api/v1/pleroma/admin/users/deactivate` ### Deactivate user @@ -248,7 +243,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `PATCH /api/pleroma/admin/users/approve` +## `PATCH /api/v1/pleroma/admin/users/approve` ### Approve user @@ -266,7 +261,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `GET /api/pleroma/admin/users/:nickname_or_id` +## `GET /api/v1/pleroma/admin/users/:nickname_or_id` ### Retrive the details of a user @@ -276,7 +271,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On failure: `Not found` - On success: JSON of the user -## `GET /api/pleroma/admin/users/:nickname_or_id/statuses` +## `GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses` ### Retrive user's latest statuses @@ -300,7 +295,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `GET /api/pleroma/admin/instances/:instance/statuses` +## `GET /api/v1/pleroma/admin/instances/:instance/statuses` ### Retrive instance's latest statuses @@ -324,7 +319,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `GET /api/pleroma/admin/statuses` +## `GET /api/v1/pleroma/admin/statuses` ### Retrives all latest statuses @@ -337,7 +332,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On failure: `Not found` - On success: JSON array of user's latest statuses -## `GET /api/pleroma/admin/relay` +## `GET /api/v1/pleroma/admin/relay` ### List Relays @@ -353,7 +348,7 @@ Response: ] ``` -## `POST /api/pleroma/admin/relay` +## `POST /api/v1/pleroma/admin/relay` ### Follow a Relay @@ -369,7 +364,7 @@ Response: {"actor": "https://example.com/relay", "followed_back": true} ``` -## `DELETE /api/pleroma/admin/relay` +## `DELETE /api/v1/pleroma/admin/relay` ### Unfollow a Relay @@ -385,7 +380,7 @@ Response: {"https://example.com/relay"} ``` -## `POST /api/pleroma/admin/users/invite_token` +## `POST /api/v1/pleroma/admin/users/invite_token` ### Create an account registration invite token @@ -406,7 +401,7 @@ Response: } ``` -## `GET /api/pleroma/admin/users/invites` +## `GET /api/v1/pleroma/admin/users/invites` ### Get a list of generated invites @@ -431,7 +426,7 @@ Response: } ``` -## `POST /api/pleroma/admin/users/revoke_invite` +## `POST /api/v1/pleroma/admin/users/revoke_invite` ### Revoke invite by token @@ -452,7 +447,7 @@ Response: } ``` -## `POST /api/pleroma/admin/users/email_invite` +## `POST /api/v1/pleroma/admin/users/email_invite` ### Sends registration invite via email @@ -473,7 +468,7 @@ Response: ] ``` -## `GET /api/pleroma/admin/users/:nickname/password_reset` +## `GET /api/v1/pleroma/admin/users/:nickname/password_reset` ### Get a password reset token for a given nickname @@ -484,11 +479,11 @@ Response: ```json { "token": "base64 reset token", - "link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token" + "link": "https://pleroma.social/api/v1/pleroma/password_reset/url-encoded-base64-token" } ``` -## `PATCH /api/pleroma/admin/users/force_password_reset` +## `PATCH /api/v1/pleroma/admin/users/force_password_reset` ### Force passord reset for a user with a given nickname @@ -496,7 +491,7 @@ Response: - `nicknames` - Response: none (code `204`) -## PUT `/api/pleroma/admin/users/disable_mfa` +## PUT `/api/v1/pleroma/admin/users/disable_mfa` ### Disable mfa for user's account. @@ -504,7 +499,7 @@ Response: - `nickname` - Response: Userâs nickname -## `GET /api/pleroma/admin/users/:nickname/credentials` +## `GET /api/v1/pleroma/admin/users/:nickname/credentials` ### Get the user's email, password, display and settings-related fields @@ -552,7 +547,7 @@ Response: } ``` -## `PATCH /api/pleroma/admin/users/:nickname/credentials` +## `PATCH /api/v1/pleroma/admin/users/:nickname/credentials` ### Change the user's email, password, display and settings-related fields @@ -603,7 +598,7 @@ Status: 404 {"error": "Not found"} ``` -## `GET /api/pleroma/admin/reports` +## `GET /api/v1/pleroma/admin/reports` ### Get a list of reports @@ -763,17 +758,17 @@ Status: 404 } ``` -## `GET /api/pleroma/admin/grouped_reports` +## `GET /api/v1/pleroma/admin/grouped_reports` ### Get a list of reports, grouped by status - Params: none - On success: JSON, returns a list of reports, where: - `date`: date of the latest report - - `account`: the user who has been reported (see `/api/pleroma/admin/reports` for reference) - - `status`: reported status (see `/api/pleroma/admin/reports` for reference) - - `actors`: users who had reported this status (see `/api/pleroma/admin/reports` for reference) - - `reports`: reports (see `/api/pleroma/admin/reports` for reference) + - `account`: the user who has been reported (see `/api/v1/pleroma/admin/reports` for reference) + - `status`: reported status (see `/api/v1/pleroma/admin/reports` for reference) + - `actors`: users who had reported this status (see `/api/v1/pleroma/admin/reports` for reference) + - `reports`: reports (see `/api/v1/pleroma/admin/reports` for reference) ```json "reports": [ @@ -787,7 +782,7 @@ Status: 404 ] ``` -## `GET /api/pleroma/admin/reports/:id` +## `GET /api/v1/pleroma/admin/reports/:id` ### Get an individual report @@ -799,7 +794,7 @@ Status: 404 - 404 Not Found `"Not found"` - On success: JSON, Report object (see above) -## `PATCH /api/pleroma/admin/reports` +## `PATCH /api/v1/pleroma/admin/reports` ### Change the state of one or multiple reports @@ -830,7 +825,7 @@ Status: 404 - On success: `204`, empty response -## `POST /api/pleroma/admin/reports/:id/notes` +## `POST /api/v1/pleroma/admin/reports/:id/notes` ### Create report note @@ -842,7 +837,7 @@ Status: 404 - 400 Bad Request `"Invalid parameters"` when `status` is missing - On success: `204`, empty response -## `DELETE /api/pleroma/admin/reports/:report_id/notes/:id` +## `DELETE /api/v1/pleroma/admin/reports/:report_id/notes/:id` ### Delete report note @@ -854,7 +849,7 @@ Status: 404 - 400 Bad Request `"Invalid parameters"` when `status` is missing - On success: `204`, empty response -## `GET /api/pleroma/admin/statuses/:id` +## `GET /api/v1/pleroma/admin/statuses/:id` ### Show status by id @@ -865,7 +860,7 @@ Status: 404 - 404 Not Found `"Not Found"` - On success: JSON, Mastodon Status entity -## `PUT /api/pleroma/admin/statuses/:id` +## `PUT /api/v1/pleroma/admin/statuses/:id` ### Change the scope of an individual reported status @@ -880,7 +875,7 @@ Status: 404 - 404 Not Found `"Not found"` - On success: JSON, Mastodon Status entity -## `DELETE /api/pleroma/admin/statuses/:id` +## `DELETE /api/v1/pleroma/admin/statuses/:id` ### Delete an individual reported status @@ -892,7 +887,7 @@ Status: 404 - 404 Not Found `"Not found"` - On success: 200 OK `{}` -## `GET /api/pleroma/admin/restart` +## `GET /api/v1/pleroma/admin/restart` ### Restarts pleroma application @@ -907,7 +902,7 @@ Status: 404 {} ``` -## `GET /api/pleroma/admin/need_reboot` +## `GET /api/v1/pleroma/admin/need_reboot` ### Returns the flag whether the pleroma should be restarted @@ -920,7 +915,7 @@ Status: 404 } ``` -## `GET /api/pleroma/admin/config` +## `GET /api/v1/pleroma/admin/config` ### Get list of merged default settings with saved in database. @@ -947,7 +942,7 @@ Status: 404 } ``` -## `POST /api/pleroma/admin/config` +## `POST /api/v1/pleroma/admin/config` ### Update config settings @@ -1096,7 +1091,7 @@ config :quack, } ``` -## ` GET /api/pleroma/admin/config/descriptions` +## ` GET /api/v1/pleroma/admin/config/descriptions` ### Get JSON with config descriptions. Loads json generated from `config/descriptions.exs`. @@ -1129,7 +1124,7 @@ Loads json generated from `config/descriptions.exs`. }] ``` -## `GET /api/pleroma/admin/moderation_log` +## `GET /api/v1/pleroma/admin/moderation_log` ### Get moderation log @@ -1159,7 +1154,7 @@ Loads json generated from `config/descriptions.exs`. ] ``` -## `POST /api/pleroma/admin/reload_emoji` +## `POST /api/v1/pleroma/admin/reload_emoji` ### Reload the instance's custom emoji @@ -1167,7 +1162,7 @@ Loads json generated from `config/descriptions.exs`. - Params: None - Response: JSON, "ok" and 200 status -## `PATCH /api/pleroma/admin/users/confirm_email` +## `PATCH /api/v1/pleroma/admin/users/confirm_email` ### Confirm users' emails @@ -1175,7 +1170,7 @@ Loads json generated from `config/descriptions.exs`. - `nicknames` - Response: Array of user nicknames -## `PATCH /api/pleroma/admin/users/resend_confirmation_email` +## `PATCH /api/v1/pleroma/admin/users/resend_confirmation_email` ### Resend confirmation email @@ -1183,13 +1178,13 @@ Loads json generated from `config/descriptions.exs`. - `nicknames` - Response: Array of user nicknames -## `GET /api/pleroma/admin/stats` +## `GET /api/v1/pleroma/admin/stats` ### Stats - Query Params: - *optional* `instance`: **string** instance hostname (without protocol) to get stats for -- Example: `https://mypleroma.org/api/pleroma/admin/stats?instance=lain.com` +- Example: `https://mypleroma.org/api/v1/pleroma/admin/stats?instance=lain.com` - Response: @@ -1204,7 +1199,7 @@ Loads json generated from `config/descriptions.exs`. } ``` -## `GET /api/pleroma/admin/oauth_app` +## `GET /api/v1/pleroma/admin/oauth_app` ### List OAuth app @@ -1236,7 +1231,7 @@ Loads json generated from `config/descriptions.exs`. ``` -## `POST /api/pleroma/admin/oauth_app` +## `POST /api/v1/pleroma/admin/oauth_app` ### Create OAuth App @@ -1269,7 +1264,7 @@ Loads json generated from `config/descriptions.exs`. } ``` -## `PATCH /api/pleroma/admin/oauth_app/:id` +## `PATCH /api/v1/pleroma/admin/oauth_app/:id` ### Update OAuth App @@ -1294,7 +1289,7 @@ Loads json generated from `config/descriptions.exs`. } ``` -## `DELETE /api/pleroma/admin/oauth_app/:id` +## `DELETE /api/v1/pleroma/admin/oauth_app/:id` ### Delete OAuth App @@ -1305,7 +1300,7 @@ Loads json generated from `config/descriptions.exs`. - On failure: - 400 Bad Request `"Invalid parameters"` when `status` is missing -## `GET /api/pleroma/admin/media_proxy_caches` +## `GET /api/v1/pleroma/admin/media_proxy_caches` ### Get a list of all banned MediaProxy URLs in Cachex @@ -1329,7 +1324,7 @@ Loads json generated from `config/descriptions.exs`. ``` -## `POST /api/pleroma/admin/media_proxy_caches/delete` +## `POST /api/v1/pleroma/admin/media_proxy_caches/delete` ### Remove a banned MediaProxy URL from Cachex @@ -1344,7 +1339,7 @@ Loads json generated from `config/descriptions.exs`. ``` -## `POST /api/pleroma/admin/media_proxy_caches/purge` +## `POST /api/v1/pleroma/admin/media_proxy_caches/purge` ### Purge a MediaProxy URL @@ -1360,7 +1355,7 @@ Loads json generated from `config/descriptions.exs`. ``` -## GET /api/pleroma/admin/users/:nickname/chats +## GET /api/v1/pleroma/admin/users/:nickname/chats ### List a user's chats @@ -1389,7 +1384,7 @@ Loads json generated from `config/descriptions.exs`. ] ``` -## GET /api/pleroma/admin/chats/:chat_id +## GET /api/v1/pleroma/admin/chats/:chat_id ### View a single chat @@ -1416,7 +1411,7 @@ Loads json generated from `config/descriptions.exs`. } ``` -## GET /api/pleroma/admin/chats/:chat_id/messages +## GET /api/v1/pleroma/admin/chats/:chat_id/messages ### List the messages in a chat @@ -1454,7 +1449,7 @@ Loads json generated from `config/descriptions.exs`. ] ``` -## DELETE /api/pleroma/admin/chats/:chat_id/messages/:message_id +## DELETE /api/v1/pleroma/admin/chats/:chat_id/messages/:message_id ### Delete a single message @@ -1481,7 +1476,7 @@ Loads json generated from `config/descriptions.exs`. } ``` -## `GET /api/pleroma/admin/instance_document/:document_name` +## `GET /api/v1/pleroma/admin/instance_document/:document_name` ### Get an instance document @@ -1495,7 +1490,7 @@ Returns the content of the document