Authentication is required and the user must be an admin.
+Configuration options:
+
+* `[: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`
### List users
}
```
-## `DELETE /api/pleroma/admin/users`
+## DEPRECATED `DELETE /api/pleroma/admin/users`
### Remove a user
- `nickname`
- Response: User’s nickname
+## `DELETE /api/pleroma/admin/users`
+
+### Remove a user
+
+- Params:
+ - `nicknames`
+- Response: Array of user nicknames
+
### Create a user
- Method: `POST`
}
```
-## `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
+## DEPRECATED `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
-### Add user in permission group
+### Add user to permission group
- Params: none
- Response:
- On failure: `{"error": "…"}`
- - On success: JSON of the `user.info`
+ - On success: JSON of the user
+
+## `POST /api/pleroma/admin/users/permission_group/:permission_group`
+
+### Add users to permission group
+
+- Params:
+ - `nicknames`: nicknames array
+- Response:
+ - On failure: `{"error": "…"}`
+ - On success: JSON of the user
+
+## DEPRECATED `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
- Params: none
- Response:
- On failure: `{"error": "…"}`
- - On success: JSON of the `user.info`
+ - On success: JSON of the user
- Note: An admin cannot revoke their own admin status.
-## `PUT /api/pleroma/admin/users/:nickname/activation_status`
+## `DELETE /api/pleroma/admin/users/permission_group/:permission_group`
-### Active or deactivate a user
+### Remove users from permission group
- Params:
- - `nickname`
- - `status` BOOLEAN field, false value means deactivation.
+ - `nicknames`: nicknames array
+- Response:
+ - On failure: `{"error": "…"}`
+ - On success: JSON of the user
+- Note: An admin cannot revoke their own admin status.
+
+## `PATCH /api/pleroma/admin/users/activate`
+
+### Activate user
+
+- Params:
+ - `nicknames`: nicknames array
+- Response:
+
+```json
+{
+ users: [
+ {
+ // user object
+ }
+ ]
+}
+```
+
+## `PATCH /api/pleroma/admin/users/deactivate`
+
+### Deactivate user
+
+- Params:
+ - `nicknames`: nicknames array
+- Response:
+
+```json
+{
+ users: [
+ {
+ // user object
+ }
+ ]
+}
+```
## `GET /api/pleroma/admin/users/:nickname_or_id`
- `nickname` or `id`
- *optional* `page_size`: number of statuses to return (default is `20`)
- *optional* `godmode`: `true`/`false` – allows to see private statuses
+ - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
+- Response:
+ - On failure: `Not found`
+ - On success: JSON array of user's latest statuses
+
+## `GET /api/pleroma/admin/instances/:instance/statuses`
+
+### Retrive instance's latest statuses
+
+- Params:
+ - `instance`: instance name
+ - *optional* `page_size`: number of statuses to return (default is `20`)
+ - *optional* `godmode`: `true`/`false` – allows to see private statuses
+ - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
+- Response:
+ - On failure: `Not found`
+ - On success: JSON array of instance's latest statuses
+
+## `GET /api/pleroma/admin/statuses`
+
+### Retrives all latest statuses
+
+- Params:
+ - *optional* `page_size`: number of statuses to return (default is `20`)
+ - *optional* `local_only`: excludes remote statuses
+ - *optional* `godmode`: `true`/`false` – allows to see private statuses
+ - *optional* `with_reblogs`: `true`/`false` – allows to see reblogs (default is false)
- Response:
- On failure: `Not found`
- On success: JSON array of user's latest statuses
- Response:
- On success: URL of the unfollowed relay
+## `GET /api/pleroma/admin/relay`
+
+### List Relays
+
+- Params: none
+- Response:
+ - On success: JSON array of relays
+
## `POST /api/pleroma/admin/users/invite_token`
### Create an account registration invite token
}
```
-## `PATCH /api/pleroma/admin/users/:nickname/force_password_reset`
+## `PATCH /api/pleroma/admin/users/force_password_reset`
### Force passord reset for a user with a given nickname
-- Params: none
+- Params:
+ - `nicknames`
- Response: none (code `204`)
+## `GET /api/pleroma/admin/users/:nickname/credentials`
+
+### Get the user's email, password, display and settings-related fields
+
+- Params:
+ - `nickname`
+
+- Response:
+
+```json
+{
+ "actor_type": "Person",
+ "allow_following_move": true,
+ "avatar": "https://pleroma.social/media/7e8e7508fd545ef580549b6881d80ec0ff2c81ed9ad37b9bdbbdf0e0d030159d.jpg",
+ "background": "https://pleroma.social/media/4de34c0bd10970d02cbdef8972bef0ebbf55f43cadc449554d4396156162fe9a.jpg",
+ "banner": "https://pleroma.social/media/8d92ba2bd244b613520abf557dd448adcd30f5587022813ee9dd068945986946.jpg",
+ "bio": "bio",
+ "default_scope": "public",
+ "discoverable": false,
+ "email": "user@example.com",
+ "fields": [
+ {
+ "name": "example",
+ "value": "<a href=\"https://example.com\" rel=\"ugc\">https://example.com</a>"
+ }
+ ],
+ "hide_favorites": false,
+ "hide_followers": false,
+ "hide_followers_count": false,
+ "hide_follows": false,
+ "hide_follows_count": false,
+ "id": "9oouHaEEUR54hls968",
+ "locked": true,
+ "name": "user",
+ "no_rich_text": true,
+ "pleroma_settings_store": {},
+ "raw_fields": [
+ {
+ "id": 1,
+ "name": "example",
+ "value": "https://example.com"
+ },
+ ],
+ "show_role": true,
+ "skip_thread_containment": false
+}
+```
+
+## `PATCH /api/pleroma/admin/users/:nickname/credentials`
+
+### Change the user's email, password, display and settings-related fields
+
+- Params:
+ - `email`
+ - `password`
+ - `name`
+ - `bio`
+ - `avatar`
+ - `locked`
+ - `no_rich_text`
+ - `default_scope`
+ - `banner`
+ - `hide_follows`
+ - `hide_followers`
+ - `hide_followers_count`
+ - `hide_follows_count`
+ - `hide_favorites`
+ - `allow_following_move`
+ - `background`
+ - `show_role`
+ - `skip_thread_containment`
+ - `fields`
+ - `discoverable`
+ - `actor_type`
+
+- Response: none (code `200`)
+
## `GET /api/pleroma/admin/reports`
### Get a list of reports
- On success: `204`, empty response
-## `POST /api/pleroma/admin/reports/:id/respond`
+## `POST /api/pleroma/admin/reports/:id/notes`
-### Respond to a report
+### Create report note
- Params:
- - `id`
- - `status`: required, the message
+ - `id`: required, report id
+ - `content`: 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
+ - On success: `204`, empty response
-```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"
-}
-```
+## `POST /api/pleroma/admin/reports/:report_id/notes/:id`
+
+### Delete report note
+
+- Params:
+ - `report_id`: required, report id
+ - `id`: required, note id
+- Response:
+ - On failure:
+ - 400 Bad Request `"Invalid parameters"` when `status` is missing
+ - On success: `204`, empty response
## `PUT /api/pleroma/admin/statuses/:id`
- 404 Not Found `"Not found"`
- On success: 200 OK `{}`
-## `GET /api/pleroma/admin/config/migrate_to_db`
-
-### Run mix task pleroma.config migrate_to_db
-
-Copy settings on key `:pleroma` to DB.
-
-- Params: none
-- Response:
-
-```json
-{}
-```
-
-## `GET /api/pleroma/admin/config/migrate_from_db`
+## `GET /api/pleroma/admin/restart`
-### Run mix task pleroma.config migrate_from_db
+### Restarts pleroma application
-Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB.
-
-- Method `GET`
- Params: none
- Response:
+ - On failure:
+ - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
```json
{}
## `GET /api/pleroma/admin/config`
-### List config settings
+### Get list of merged default settings with saved in database.
-List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
+*If `need_reboot` flag exists in response, instance must be restarted, so reboot time settings can take effect.*
-- Params: none
+**Only works when configuration from database is enabled.**
+
+- Params:
+ - `only_db`: true (*optional*, get only saved in database settings)
- Response:
+ - On failure:
+ - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
```json
{
- configs: [
+ "configs": [
{
- "group": string,
- "key": string or string with leading `:` for atoms,
- "value": string or {} or [] or {"tuple": []}
+ "group": ":pleroma",
+ "key": "Pleroma.Upload",
+ "value": []
}
- ]
+ ],
+ "need_reboot": true
}
```
+ need_reboot - *optional*, if were changed reboot time settings.
## `POST /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 `need_reboot` flag exists in response, instance must be restarted, so reboot time settings can take effect.*
-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"]}.
+**Only works when configuration from database is enabled.**
-Compile time settings (need instance reboot):
-- all settings by this keys:
+Some modifications are necessary to save the config settings correctly:
+
+- strings which start with `Pleroma.`, `Phoenix.`, `Tesla.` or strings like `Oban`, `Ueberauth` will be converted to modules;
+```
+"Pleroma.Upload" -> Pleroma.Upload
+"Oban" -> Oban
+```
+- strings starting with `:` will be converted to atoms;
+```
+":pleroma" -> :pleroma
+```
+- objects with `tuple` key and array value will be converted to tuples;
+```
+{"tuple": ["string", "Pleroma.Upload", []]} -> {"string", Pleroma.Upload, []}
+```
+- arrays with *tuple objects* will be converted to keywords;
+```
+[{"tuple": [":key1", "value"]}, {"tuple": [":key2", "value"]}] -> [key1: "value", key2: "value"]
+```
+
+Most of the settings will be applied in `runtime`, this means that you don't need to restart the instance. But some settings are applied in `compile time` and require a reboot of the instance, such as:
+- all settings inside these keys:
- `:hackney_pools`
+ - `:connections_pool`
+ - `:pools`
- `:chat`
- - `Pleroma.Web.Endpoint`
- - `Pleroma.Repo`
-- part settings:
- - `Pleroma.Captcha` -> `:seconds_valid`
- - `Pleroma.Upload` -> `:proxy_remote`
- - `:instance` -> `:upload_limit`
-
-- 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)
+- partially settings inside these keys:
+ - `:seconds_valid` in `Pleroma.Captcha`
+ - `:proxy_remote` in `Pleroma.Upload`
+ - `:upload_limit` in `:instance`
+
+- Params:
+ - `configs` - array of config objects
+ - config object params:
+ - `group` - string (**required**)
+ - `key` - string (**required**)
+ - `value` - string, [], {} or {"tuple": []} (**required**)
+ - `delete` - true (*optional*, if setting must be deleted)
+ - `subkeys` - array of strings (*optional*, only works when `delete=true` parameter is passed, otherwise will be ignored)
+
+*When a value have several nested settings, you can delete only some nested settings by passing a parameter `subkeys`, without deleting all settings by key.*
+```
+[subkey: val1, subkey2: val2, subkey3: val3] \\ initial value
+{"group": ":pleroma", "key": "some_key", "delete": true, "subkeys": [":subkey", ":subkey3"]} \\ passing json for deletion
+[subkey2: val2] \\ value after deletion
+```
+
+*Most of the settings can be partially updated through merge old values with new values, except settings value of which is list or is not keyword.*
+
+Example of setting without keyword in value:
+```elixir
+config :tesla, :adapter, Tesla.Adapter.Hackney
+```
+
+List of settings which support only full update by key:
+```elixir
+@full_key_update [
+ {:pleroma, :ecto_repos},
+ {:quack, :meta},
+ {:mime, :types},
+ {:cors_plug, [:max_age, :methods, :expose, :headers]},
+ {:auto_linker, :opts},
+ {:swarm, :node_blacklist},
+ {:logger, :backends}
]
+```
-- Request (example):
+List of settings which support only full update by subkey:
+```elixir
+@full_subkey_update [
+ {:pleroma, :assets, :mascots},
+ {:pleroma, :emoji, :groups},
+ {:pleroma, :workers, :retries},
+ {:pleroma, :mrf_subchain, :match_actor},
+ {:pleroma, :mrf_keyword, :replace}
+ ]
+```
+*Settings without explicit key must be sended in separate config object params.*
+```elixir
+config :quack,
+ level: :debug,
+ meta: [:all],
+ ...
+```
```json
{
- configs: [
+ "configs": [
+ {"group": ":quack", "key": ":level", "value": ":debug"},
+ {"group": ":quack", "key": ":meta", "value": [":all"]},
+ ...
+ ]
+}
+```
+- Request:
+
+```json
+{
+ "configs": [
{
- "group": "pleroma",
+ "group": ":pleroma",
"key": "Pleroma.Upload",
"value": [
{"tuple": [":uploader", "Pleroma.Uploaders.Local"]},
{"tuple": [":proxy_opts", [
{"tuple": [":redirect_on_failure", false]},
{"tuple": [":max_body_length", 1048576]},
- {"tuple": [":http": [
+ {"tuple": [":http", [
{"tuple": [":follow_redirect", true]},
{"tuple": [":pool", ":upload"]},
]]}
```
- Response:
-
+ - On failure:
+ - 400 Bad Request `"To use this endpoint you need to enable configuration from database."`
```json
{
- configs: [
+ "configs": [
{
- "group": string,
- "key": string or string with leading `:` for atoms,
- "value": string or {} or [] or {"tuple": []}
+ "group": ":pleroma",
+ "key": "Pleroma.Upload",
+ "value": [...]
}
- ]
+ ],
+ "need_reboot": true
}
```
+need_reboot - *optional*, if were changed reboot time settings.
+
+## ` GET /api/pleroma/admin/config/descriptions`
+
+### Get JSON with config descriptions.
+Loads json generated from `config/descriptions.exs`.
+
+- Params: none
+- Response:
+
+```json
+[{
+ "group": ":pleroma", // string
+ "key": "ModuleName", // string
+ "type": "group", // string or list with possible values,
+ "description": "Upload general settings", // string
+ "children": [
+ {
+ "key": ":uploader", // string or module name `Pleroma.Upload`
+ "type": "module",
+ "description": "Module which will be used for uploads",
+ "suggestions": ["module1", "module2"]
+ },
+ {
+ "key": ":filters",
+ "type": ["list", "module"],
+ "description": "List of filter modules for uploads",
+ "suggestions": [
+ "module1", "module2", "module3"
+ ]
+ }
+ ]
+}]
+```
## `GET /api/pleroma/admin/moderation_log`
- Authentication: required
- Params: None
- Response: JSON, "ok" and 200 status
+
+## `PATCH /api/pleroma/admin/users/confirm_email`
+
+### Confirm users' emails
+
+- Params:
+ - `nicknames`
+- Response: Array of user nicknames
+
+## `PATCH /api/pleroma/admin/users/resend_confirmation_email`
+
+### Resend confirmation email
+
+- Params:
+ - `nicknames`
+- Response: Array of user nicknames
+
+## `GET /api/pleroma/admin/stats`
+
+### Stats
+
+- Response:
+
+```json
+{
+ "status_visibility": {
+ "direct": 739,
+ "private": 9,
+ "public": 17,
+ "unlisted": 14
+ }
+}
+```
projects / akkoma / blobdiff