X-Git-Url: http://git.squeep.com/?a=blobdiff_plain;f=docs%2Fapi%2Fadmin_api.md;h=7ccb9083608d5703d41759ba6534445d7709d1d1;hb=83a3de8cc4edc6992bbc334cda57de13caa971b0;hp=75fa2ee83e3e32ffdc5126c02cb6f6fd9a2ed70b;hpb=16cb9e5f1cae84322bd7953e58b438f3b4bd8b9c;p=akkoma diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 75fa2ee83..7ccb90836 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -24,7 +24,7 @@ Authentication is required and the user must be an admin. - 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` - Response: -```JSON +```json { "page_size": integer, "count": integer, @@ -38,7 +38,9 @@ Authentication is required and the user must be an admin. "moderator": bool }, "local": bool, - "tags": array + "tags": array, + "avatar": string, + "display_name": string }, ... ] @@ -92,7 +94,7 @@ Authentication is required and the user must be an admin. - `nickname` - Response: User’s object -```JSON +```json { "deactivated": bool, "id": integer, @@ -106,15 +108,15 @@ Authentication is required and the user must be an admin. - Method: `PUT` - Params: - - `nickname` - - `tags` + - `nicknames` (array) + - `tags` (array) ### Untag a list of users - Method: `DELETE` - Params: - - `nickname` - - `tags` + - `nicknames` (array) + - `tags` (array) ## `/api/pleroma/admin/users/:nickname/permission_group` @@ -124,7 +126,7 @@ Authentication is required and the user must be an admin. - Params: none - Response: -```JSON +```json { "is_moderator": bool, "is_admin": bool @@ -141,7 +143,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Params: none - Response: -```JSON +```json { "is_moderator": bool, "is_admin": bool @@ -174,17 +176,30 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `nickname` - `status` BOOLEAN field, false value means deactivation. -## `/api/pleroma/admin/users/:nickname` +## `/api/pleroma/admin/users/:nickname_or_id` ### Retrive the details of a user - Method: `GET` - Params: - - `nickname` + - `nickname` or `id` - Response: - On failure: `Not found` - On success: JSON of the user +## `/api/pleroma/admin/users/:nickname_or_id/statuses` + +### Retrive user's latest statuses + +- Method: `GET` +- Params: + - `nickname` or `id` + - *optional* `page_size`: number of statuses to return (default is `20`) + - *optional* `godmode`: `true`/`false` – allows to see private statuses +- Response: + - On failure: `Not found` + - On success: JSON array of user's latest statuses + ## `/api/pleroma/admin/relay` ### Follow a Relay @@ -223,7 +238,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Params: none - Response: -```JSON +```json { "invites": [ @@ -250,7 +265,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `token` - Response: -```JSON +```json { "id": integer, "token": string, @@ -280,3 +295,402 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Methods: `GET` - Params: none - Response: password reset token (base64 string) + +## `/api/pleroma/admin/reports` +### Get a list of reports +- Method `GET` +- Params: + - `state`: optional, the state of reports. Valid values are `open`, `closed` and `resolved` + - `limit`: optional, the number of records to retrieve + - `since_id`: optional, returns results that are more recent than the specified id + - `max_id`: optional, returns results that are older than the specified id +- Response: + - On failure: 403 Forbidden error `{"error": "error_msg"}` when requested by anonymous or non-admin + - On success: JSON, returns a list of reports, where: + - `account`: the user who has been reported + - `actor`: the user who has sent the report + - `statuses`: list of statuses that have been included to the report + +```json +{ + "reports": [ + { + "account": { + "acct": "user", + "avatar": "https://pleroma.example.org/images/avi.png", + "avatar_static": "https://pleroma.example.org/images/avi.png", + "bot": false, + "created_at": "2019-04-23T17:32:04.000Z", + "display_name": "User", + "emojis": [], + "fields": [], + "followers_count": 1, + "following_count": 1, + "header": "https://pleroma.example.org/images/banner.png", + "header_static": "https://pleroma.example.org/images/banner.png", + "id": "9i6dAJqSGSKMzLG2Lo", + "locked": false, + "note": "", + "pleroma": { + "confirmation_pending": false, + "hide_favorites": true, + "hide_followers": false, + "hide_follows": false, + "is_admin": false, + "is_moderator": false, + "relationship": {}, + "tags": [] + }, + "source": { + "note": "", + "pleroma": {}, + "sensitive": false + }, + "tags": ["force_unlisted"], + "statuses_count": 3, + "url": "https://pleroma.example.org/users/user", + "username": "user" + }, + "actor": { + "acct": "lain", + "avatar": "https://pleroma.example.org/images/avi.png", + "avatar_static": "https://pleroma.example.org/images/avi.png", + "bot": false, + "created_at": "2019-03-28T17:36:03.000Z", + "display_name": "Roger Braun", + "emojis": [], + "fields": [], + "followers_count": 1, + "following_count": 1, + "header": "https://pleroma.example.org/images/banner.png", + "header_static": "https://pleroma.example.org/images/banner.png", + "id": "9hEkA5JsvAdlSrocam", + "locked": false, + "note": "", + "pleroma": { + "confirmation_pending": false, + "hide_favorites": false, + "hide_followers": false, + "hide_follows": false, + "is_admin": false, + "is_moderator": false, + "relationship": {}, + "tags": [] + }, + "source": { + "note": "", + "pleroma": {}, + "sensitive": false + }, + "tags": ["force_unlisted"], + "statuses_count": 1, + "url": "https://pleroma.example.org/users/lain", + "username": "lain" + }, + "content": "Please delete it", + "created_at": "2019-04-29T19:48:15.000Z", + "id": "9iJGOv1j8hxuw19bcm", + "state": "open", + "statuses": [ + { + "account": { ... }, + "application": { + "name": "Web", + "website": null + }, + "bookmarked": false, + "card": null, + "content": "@lain click on my link https://www.google.com/", + "created_at": "2019-04-23T19:15:47.000Z", + "emojis": [], + "favourited": false, + "favourites_count": 0, + "id": "9i6mQ9uVrrOmOime8m", + "in_reply_to_account_id": null, + "in_reply_to_id": null, + "language": null, + "media_attachments": [], + "mentions": [ + { + "acct": "lain", + "id": "9hEkA5JsvAdlSrocam", + "url": "https://pleroma.example.org/users/lain", + "username": "lain" + }, + { + "acct": "user", + "id": "9i6dAJqSGSKMzLG2Lo", + "url": "https://pleroma.example.org/users/user", + "username": "user" + } + ], + "muted": false, + "pinned": false, + "pleroma": { + "content": { + "text/plain": "@lain click on my link https://www.google.com/" + }, + "conversation_id": 28, + "in_reply_to_account_acct": null, + "local": true, + "spoiler_text": { + "text/plain": "" + } + }, + "reblog": null, + "reblogged": false, + "reblogs_count": 0, + "replies_count": 0, + "sensitive": false, + "spoiler_text": "", + "tags": [], + "uri": "https://pleroma.example.org/objects/8717b90f-8e09-4b58-97b0-e3305472b396", + "url": "https://pleroma.example.org/notice/9i6mQ9uVrrOmOime8m", + "visibility": "direct" + } + ] + } + ] +} +``` + +## `/api/pleroma/admin/reports/:id` +### Get an individual report +- Method `GET` +- Params: + - `id` +- Response: + - On failure: + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, Report object (see above) + +## `/api/pleroma/admin/reports/:id` +### Change the state of the report +- Method `PUT` +- Params: + - `id` + - `state`: required, the new state. Valid values are `open`, `closed` and `resolved` +- Response: + - On failure: + - 400 Bad Request `"Unsupported state"` + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, Report object (see above) + +## `/api/pleroma/admin/reports/:id/respond` +### Respond to a report +- Method `POST` +- Params: + - `id` + - `status`: required, the message +- Response: + - On failure: + - 400 Bad Request `"Invalid parameters"` when `status` is missing + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, created Mastodon Status entity + +```json +{ + "account": { ... }, + "application": { + "name": "Web", + "website": null + }, + "bookmarked": false, + "card": null, + "content": "Your claim is going to be closed", + "created_at": "2019-05-11T17:13:03.000Z", + "emojis": [], + "favourited": false, + "favourites_count": 0, + "id": "9ihuiSL1405I65TmEq", + "in_reply_to_account_id": null, + "in_reply_to_id": null, + "language": null, + "media_attachments": [], + "mentions": [ + { + "acct": "user", + "id": "9i6dAJqSGSKMzLG2Lo", + "url": "https://pleroma.example.org/users/user", + "username": "user" + }, + { + "acct": "admin", + "id": "9hEkA5JsvAdlSrocam", + "url": "https://pleroma.example.org/users/admin", + "username": "admin" + } + ], + "muted": false, + "pinned": false, + "pleroma": { + "content": { + "text/plain": "Your claim is going to be closed" + }, + "conversation_id": 35, + "in_reply_to_account_acct": null, + "local": true, + "spoiler_text": { + "text/plain": "" + } + }, + "reblog": null, + "reblogged": false, + "reblogs_count": 0, + "replies_count": 0, + "sensitive": false, + "spoiler_text": "", + "tags": [], + "uri": "https://pleroma.example.org/objects/cab0836d-9814-46cd-a0ea-529da9db5fcb", + "url": "https://pleroma.example.org/notice/9ihuiSL1405I65TmEq", + "visibility": "direct" +} +``` + +## `/api/pleroma/admin/statuses/:id` +### Change the scope of an individual reported status +- Method `PUT` +- Params: + - `id` + - `sensitive`: optional, valid values are `true` or `false` + - `visibility`: optional, valid values are `public`, `private` and `unlisted` +- Response: + - On failure: + - 400 Bad Request `"Unsupported visibility"` + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: JSON, Mastodon Status entity + +## `/api/pleroma/admin/statuses/:id` +### Delete an individual reported status +- Method `DELETE` +- Params: + - `id` +- Response: + - On failure: + - 403 Forbidden `{"error": "error_msg"}` + - 404 Not Found `"Not found"` + - On success: 200 OK `{}` + + +## `/api/pleroma/admin/config/migrate_to_db` +### Run mix task pleroma.config migrate_to_db +Copy settings on key `:pleroma` to DB. +- Method `GET` +- Params: none +- Response: + +```json +{} +``` + +## `/api/pleroma/admin/config/migrate_from_db` +### Run mix task pleroma.config migrate_from_db +Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB. +- Method `GET` +- Params: none +- Response: + +```json +{} +``` + +## `/api/pleroma/admin/config` +### List config settings +List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. +- Method `GET` +- Params: none +- Response: + +```json +{ + configs: [ + { + "group": string, + "key": string or string with leading `:` for atoms, + "value": string or {} or [] or {"tuple": []} + } + ] +} +``` + +## `/api/pleroma/admin/config` +### Update config settings +Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. +Module name can be passed as string, which starts with `Pleroma`, e.g. `"Pleroma.Upload"`. +Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`. +Tuples can be passed as `{"tuple": ["first_val", Pleroma.Module, []]}`. +`{"tuple": ["some_string", "Pleroma.Some.Module", []]}` will be converted to `{"some_string", Pleroma.Some.Module, []}`. +Keywords can be passed as lists with 2 child tuples, e.g. +`[{"tuple": ["first_val", Pleroma.Module]}, {"tuple": ["second_val", true]}]`. + +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.: +{"group": "pleroma", "key": "some_key", "delete": "true", "subkeys": [":subkey", ":subkey3"]}. + +Compile time settings (need instance reboot): +- all settings by this keys: + - `:hackney_pools` + - `:chat` + - `Pleroma.Web.Endpoint` + - `Pleroma.Repo` +- part settings: + - `Pleroma.Captcha` -> `:seconds_valid` + - `Pleroma.Upload` -> `:proxy_remote` + - `:instance` -> `:upload_limit` + +- Method `POST` +- Params: + - `configs` => [ + - `group` (string) + - `key` (string or string with leading `:` for atoms) + - `value` (string, [], {} or {"tuple": []}) + - `delete` = true (optional, if parameter must be deleted) + - `subkeys` [(string with leading `:` for atoms)] (optional, works only if `delete=true` parameter is passed, otherwise will be ignored) + ] + +- Request (example): + +```json +{ + configs: [ + { + "group": "pleroma", + "key": "Pleroma.Upload", + "value": [ + {"tuple": [":uploader", "Pleroma.Uploaders.Local"]}, + {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]}, + {"tuple": [":link_name", true]}, + {"tuple": [":proxy_remote", false]}, + {"tuple": [":proxy_opts", [ + {"tuple": [":redirect_on_failure", false]}, + {"tuple": [":max_body_length", 1048576]}, + {"tuple": [":http": [ + {"tuple": [":follow_redirect", true]}, + {"tuple": [":pool", ":upload"]}, + ]]} + ] + ]}, + {"tuple": [":dispatch", { + "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []] + }]} + ] + } + ] +} + +- Response: + +```json +{ + configs: [ + { + "group": string, + "key": string or string with leading `:` for atoms, + "value": string or {} or [] or {"tuple": []} + } + ] +} +```