sergiotarxz/Pleroma
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Move HTTP verb to the header (admin_api.md)

Browse Source
This commit is contained in:
Maxim Filippov 2019-10-04 18:58:44 +03:00
parent c5e937b156
commit 795ea5dfc2
1 changed files with 109 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
docs/api/admin_api.md
View File

@ -2,11 +2,10 @@
Authentication is required and the user must be an admin. Authentication is required and the user must be an admin.
## `/api/pleroma/admin/users` ## `GET /api/pleroma/admin/users`
### List users ### List users
- Method `GET`
- Query Params: - Query Params:
- *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain) - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
- *optional* `filters`: **string** comma-separated string of filters: - *optional* `filters`: **string** comma-separated string of filters:
@ -47,11 +46,10 @@ Authentication is required and the user must be an admin.
} }
``` ```
## `/api/pleroma/admin/users` ## `DELETE /api/pleroma/admin/users`
### Remove a user ### Remove a user
- Method `DELETE`
- Params: - Params:
- `nickname` - `nickname`
- Response: User’s nickname - Response: User’s nickname
@ -69,31 +67,30 @@ Authentication is required and the user must be an admin.
] ]
- Response: User’s nickname - Response: User’s nickname
## `/api/pleroma/admin/users/follow` ## `POST /api/pleroma/admin/users/follow`
### Make a user follow another user ### Make a user follow another user
- Methods: `POST`
- Params: - Params:
- `follower`: The nickname of the follower - `follower`: The nickname of the follower
- `followed`: The nickname of the followed - `followed`: The nickname of the followed
- Response: - Response:
- "ok" - "ok"
## `/api/pleroma/admin/users/unfollow` ## `POST /api/pleroma/admin/users/unfollow`
### Make a user unfollow another user ### Make a user unfollow another user
- Methods: `POST`
- Params: - Params:
- `follower`: The nickname of the follower - `follower`: The nickname of the follower
- `followed`: The nickname of the followed - `followed`: The nickname of the followed
- Response: - Response:
- "ok" - "ok"
## `/api/pleroma/admin/users/:nickname/toggle_activation` ## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation`
### Toggle user activation ### Toggle user activation
- Method: `PATCH`
- Params: - Params:
- `nickname` - `nickname`
- Response: User’s object - Response: User’s object
@ -106,27 +103,26 @@ Authentication is required and the user must be an admin.
} }
``` ```
## `/api/pleroma/admin/users/tag` ## `PUT /api/pleroma/admin/users/tag`
### Tag a list of users ### Tag a list of users
- Method: `PUT`
- Params: - Params:
- `nicknames` (array) - `nicknames` (array)
- `tags` (array) - `tags` (array)
## `DELETE /api/pleroma/admin/users/tag`
### Untag a list of users ### Untag a list of users
- Method: `DELETE`
- Params: - Params:
- `nicknames` (array) - `nicknames` (array)
- `tags` (array) - `tags` (array)
## `/api/pleroma/admin/users/:nickname/permission_group` ## `GET /api/pleroma/admin/users/:nickname/permission_group`
### Get user user permission groups membership ### Get user user permission groups membership
- Method: `GET`
- Params: none - Params: none
- Response: - Response:
@ -137,13 +133,12 @@ Authentication is required and the user must be an admin.
} }
``` ```
## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group` ## `GET /api/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. Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist.
### Get user user permission groups membership per permission group ### Get user user permission groups membership per permission group
- Method: `GET`
- Params: none - Params: none
- Response: - Response:
@ -154,48 +149,47 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
### Add user in permission group ### Add user in permission group
- Method: `POST`
- Params: none - Params: none
- Response: - Response:
- On failure: `{"error": "…"}` - On failure: `{"error": "…"}`
- On success: JSON of the `user.info` - On success: JSON of the `user.info`
## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
### Remove user from permission group ### Remove user from permission group
- Method: `DELETE`
- Params: none - Params: none
- Response: - Response:
- On failure: `{"error": "…"}` - On failure: `{"error": "…"}`
- On success: JSON of the `user.info` - On success: JSON of the `user.info`
- Note: An admin cannot revoke their own admin status. - Note: An admin cannot revoke their own admin status.
## `/api/pleroma/admin/users/:nickname/activation_status` ## `PUT /api/pleroma/admin/users/:nickname/activation_status`
### Active or deactivate a user ### Active or deactivate a user
- Method: `PUT`
- Params: - Params:
- `nickname` - `nickname`
- `status` BOOLEAN field, false value means deactivation. - `status` BOOLEAN field, false value means deactivation.
## `/api/pleroma/admin/users/:nickname_or_id` ## `GET /api/pleroma/admin/users/:nickname_or_id`
### Retrive the details of a user ### Retrive the details of a user
- Method: `GET`
- Params: - Params:
- `nickname` or `id` - `nickname` or `id`
- Response: - Response:
- On failure: `Not found` - On failure: `Not found`
- On success: JSON of the user - On success: JSON of the user
## `/api/pleroma/admin/users/:nickname_or_id/statuses` ## `GET /api/pleroma/admin/users/:nickname_or_id/statuses`
### Retrive user's latest statuses ### Retrive user's latest statuses
- Method: `GET`
- Params: - Params:
- `nickname` or `id` - `nickname` or `id`
- *optional* `page_size`: number of statuses to return (default is `20`) - *optional* `page_size`: number of statuses to return (default is `20`)
@ -204,29 +198,28 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- On failure: `Not found` - On failure: `Not found`
- On success: JSON array of user's latest statuses - On success: JSON array of user's latest statuses
## `/api/pleroma/admin/relay` ## `POST /api/pleroma/admin/relay`
### Follow a Relay ### Follow a Relay
- Methods: `POST`
- Params: - Params:
- `relay_url` - `relay_url`
- Response: - Response:
- On success: URL of the followed relay - On success: URL of the followed relay
## `DELETE /api/pleroma/admin/relay`
### Unfollow a Relay ### Unfollow a Relay
- Methods: `DELETE`
- Params: - Params:
- `relay_url` - `relay_url`
- Response: - Response:
- On success: URL of the unfollowed relay - On success: URL of the unfollowed relay
## `/api/pleroma/admin/users/invite_token` ## `POST /api/pleroma/admin/users/invite_token`
### Create an account registration invite token ### Create an account registration invite token
- Methods: `POST`
- Params: - Params:
- *optional* `max_use` (integer) - *optional* `max_use` (integer)
- *optional* `expires_at` (date string e.g. "2019-04-07") - *optional* `expires_at` (date string e.g. "2019-04-07")
@ -244,11 +237,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `/api/pleroma/admin/users/invites` ## `GET /api/pleroma/admin/users/invites`
### Get a list of generated invites ### Get a list of generated invites
- Methods: `GET`
- Params: none - Params: none
- Response: - Response:
@ -270,11 +262,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `/api/pleroma/admin/users/revoke_invite` ## `POST /api/pleroma/admin/users/revoke_invite`
### Revoke invite by token ### Revoke invite by token
- Methods: `POST`
- Params: - Params:
- `token` - `token`
- Response: - Response:
@ -292,21 +283,18 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `POST /api/pleroma/admin/users/email_invite`
## `/api/pleroma/admin/users/email_invite`
### Sends registration invite via email ### Sends registration invite via email
- Methods: `POST`
- Params: - Params:
- `email` - `email`
- `name`, optional - `name`, optional
## `/api/pleroma/admin/users/:nickname/password_reset` ## `GET /api/pleroma/admin/users/:nickname/password_reset`
### Get a password reset token for a given nickname ### Get a password reset token for a given nickname
- Methods: `GET`
- Params: none - Params: none
- Response: - Response:
@ -317,18 +305,17 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `PATCH /api/pleroma/admin/users/:nickname/force_password_reset`
## `/api/pleroma/admin/users/:nickname/force_password_reset`
### Force passord reset for a user with a given nickname ### Force passord reset for a user with a given nickname
- Methods: `PATCH`
- Params: none - Params: none
- Response: none (code `204`) - Response: none (code `204`)
## `/api/pleroma/admin/reports` ## `GET /api/pleroma/admin/reports`
### Get a list of reports ### Get a list of reports
- Method `GET`
- Params: - Params:
- *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved` - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
- *optional* `limit`: **integer** the number of records to retrieve - *optional* `limit`: **integer** the number of records to retrieve
@ -343,7 +330,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
```json ```json
{ {
"total" : 1, "totalReports" : 1,
"reports": [ "reports": [
{ {
"account": { "account": {
@ -481,13 +468,24 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
] ]
} }
],
"totalGroupedReports": 1,
"groupedReports": [
{
"date": "2019-01-01", // date of the latest report
"account": { ... }, // author of the reported status
"status": { ... }, // reported status
"actors": [{ ... }, { ... }], // accounts that sent reports on the status
"reports": [{ ... }]
}
] ]
} }
``` ```
## `/api/pleroma/admin/reports/:id` ## `GET /api/pleroma/admin/reports/:id`
### Get an individual report ### Get an individual report
- Method `GET`
- Params: - Params:
- `id` - `id`
- Response: - Response:
@ -496,22 +494,41 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- 404 Not Found `"Not found"` - 404 Not Found `"Not found"`
- On success: JSON, Report object (see above) - On success: JSON, Report object (see above)
## `/api/pleroma/admin/reports/:id` ## `PATCH /api/pleroma/admin/reports`
### Change the state of the report
- Method `PUT` ### Change the state of one or multiple reports
- Params: - Params:
- `id`
- `state`: required, the new state. Valid values are `open`, `closed` and `resolved` ```json
`reports`: [
{
`id`, // required, report id
`state` // required, the new state. Valid values are `open`, `closed` and `resolved`
},
...
]
```
- Response: - Response:
- On failure: - On failure:
- 400 Bad Request `"Unsupported state"` - 400 Bad Request, JSON:
- 403 Forbidden `{"error": "error_msg"}`
- 404 Not Found `"Not found"` ```json
- On success: JSON, Report object (see above) [
{
`id`, // report id
`error` // error message
}
]
```
- On success: `204`, empty response
## `POST /api/pleroma/admin/reports/:id/respond`
## `/api/pleroma/admin/reports/:id/respond`
### Respond to a report ### Respond to a report
- Method `POST`
- Params: - Params:
- `id` - `id`
- `status`: required, the message - `status`: required, the message
@ -581,9 +598,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `/api/pleroma/admin/statuses/:id` ## `PUT /api/pleroma/admin/statuses/:id`
### Change the scope of an individual reported status ### Change the scope of an individual reported status
- Method `PUT`
- Params: - Params:
- `id` - `id`
- `sensitive`: optional, valid values are `true` or `false` - `sensitive`: optional, valid values are `true` or `false`
@ -595,9 +613,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- 404 Not Found `"Not found"` - 404 Not Found `"Not found"`
- On success: JSON, Mastodon Status entity - On success: JSON, Mastodon Status entity
## `/api/pleroma/admin/statuses/:id` ## `DELETE /api/pleroma/admin/statuses/:id`
### Delete an individual reported status ### Delete an individual reported status
- Method `DELETE`
- Params: - Params:
- `id` - `id`
- Response: - Response:
@ -606,11 +625,12 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- 404 Not Found `"Not found"` - 404 Not Found `"Not found"`
- On success: 200 OK `{}` - On success: 200 OK `{}`
## `GET /api/pleroma/admin/config/migrate_to_db`
## `/api/pleroma/admin/config/migrate_to_db`
### Run mix task pleroma.config migrate_to_db ### Run mix task pleroma.config migrate_to_db
Copy settings on key `:pleroma` to DB. Copy settings on key `:pleroma` to DB.
- Method `GET`
- Params: none - Params: none
- Response: - Response:
@ -618,9 +638,12 @@ Copy settings on key `:pleroma` to DB.
{} {}
``` ```
## `/api/pleroma/admin/config/migrate_from_db` ## `GET /api/pleroma/admin/config/migrate_from_db`
### Run mix task pleroma.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. Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with deletion from DB.
- Method `GET` - Method `GET`
- Params: none - Params: none
- Response: - Response:
@ -629,10 +652,12 @@ Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with dele
{} {}
``` ```
## `/api/pleroma/admin/config` ## `GET /api/pleroma/admin/config`
### List config settings ### List config settings
List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`.
- Method `GET`
- Params: none - Params: none
- Response: - Response:
@ -648,8 +673,10 @@ List config settings only works with `:pleroma => :instance => :dynamic_configur
} }
``` ```
## `/api/pleroma/admin/config` ## `POST /api/pleroma/admin/config`
### Update config settings ### Update config settings
Updating config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. 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"`. 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"`. Atom keys and values can be passed with `:` in the beginning, e.g. `":upload"`.
@ -672,7 +699,6 @@ Compile time settings (need instance reboot):
- `Pleroma.Upload` -> `:proxy_remote` - `Pleroma.Upload` -> `:proxy_remote`
- `:instance` -> `:upload_limit` - `:instance` -> `:upload_limit`
- Method `POST`
- Params: - Params:
- `configs` => [ - `configs` => [
- `group` (string) - `group` (string)
@ -727,9 +753,10 @@ Compile time settings (need instance reboot):
} }
``` ```
## `/api/pleroma/admin/moderation_log` ## `GET /api/pleroma/admin/moderation_log`
### Get moderation log ### Get moderation log
- Method `GET`
- Params: - Params:
- *optional* `page`: **integer** page number - *optional* `page`: **integer** page number
- *optional* `page_size`: **integer** number of log entries per page (default is `50`) - *optional* `page_size`: **integer** number of log entries per page (default is `50`)
@ -756,8 +783,9 @@ Compile time settings (need instance reboot):
``` ```
## `POST /api/pleroma/admin/reload_emoji` ## `POST /api/pleroma/admin/reload_emoji`
### Reload the instance's custom emoji ### Reload the instance's custom emoji
* Method `POST`
* Authentication: required - Authentication: required
* Params: None - Params: None
* Response: JSON, "ok" and 200 status - Response: JSON, "ok" and 200 status