diff options
Diffstat (limited to 'docs/API')
| -rw-r--r-- | docs/API/admin_api.md | 785 | ||||
| -rw-r--r-- | docs/API/differences_in_mastoapi_responses.md | 90 | ||||
| -rw-r--r-- | docs/API/pleroma_api.md | 264 |
3 files changed, 825 insertions, 314 deletions
diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md index 6adeda07e..c455047cc 100644 --- a/docs/API/admin_api.md +++ b/docs/API/admin_api.md @@ -2,11 +2,17 @@ Authentication is required and the user must be an admin. -## `/api/pleroma/admin/users` +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 -- Method `GET` - Query Params: - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain) - *optional* `filters`: **string** comma-separated string of filters: @@ -51,7 +57,6 @@ Authentication is required and the user must be an admin. ### Remove a user -- Method `DELETE` - Params: - `nickname` - Response: User’s nickname @@ -60,7 +65,6 @@ Authentication is required and the user must be an admin. ### Remove a user -- Method `DELETE` - Params: - `nicknames` - Response: Array of user nicknames @@ -78,31 +82,30 @@ Authentication is required and the user must be an admin. ] - Response: User’s nickname -## `/api/pleroma/admin/users/follow` +## `POST /api/pleroma/admin/users/follow` + ### Make a user follow another user -- Methods: `POST` - Params: - - `follower`: The nickname of the follower - - `followed`: The nickname of the followed + - `follower`: The nickname of the follower + - `followed`: The nickname of the followed - Response: - - "ok" + - "ok" + +## `POST /api/pleroma/admin/users/unfollow` -## `/api/pleroma/admin/users/unfollow` ### Make a user unfollow another user -- Methods: `POST` - Params: - - `follower`: The nickname of the follower - - `followed`: The nickname of the followed + - `follower`: The nickname of the follower + - `followed`: The nickname of the followed - Response: - - "ok" + - "ok" -## `/api/pleroma/admin/users/:nickname/toggle_activation` +## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation` ### Toggle user activation -- Method: `PATCH` - Params: - `nickname` - Response: User’s object @@ -115,27 +118,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 -- Method: `PUT` - Params: - `nicknames` (array) - `tags` (array) +## `DELETE /api/pleroma/admin/users/tag` + ### Untag a list of users -- Method: `DELETE` - Params: - `nicknames` (array) - `tags` (array) -## `/api/pleroma/admin/users/:nickname/permission_group` +## `GET /api/pleroma/admin/users/:nickname/permission_group` ### Get user user permission groups membership -- Method: `GET` - Params: none - Response: @@ -146,13 +148,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. ### Get user user permission groups membership per permission group -- Method: `GET` - Params: none - Response: @@ -170,7 +171,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - 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` @@ -180,16 +181,18 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `nicknames`: nicknames array - Response: - On failure: `{"error": "…"}` - - On success: JSON of the `user.info` + - 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` + ### Remove user from 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. ## `DELETE /api/pleroma/admin/users/permission_group/:permission_group` @@ -200,7 +203,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `nicknames`: nicknames array - 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. ## `PATCH /api/pleroma/admin/users/activate` @@ -239,51 +242,68 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## DEPRECATED `PATCH /api/pleroma/admin/users/:nickname/activation_status` - -### Active or deactivate a user - -- Params: - - `nickname` - - `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 -- Method: `GET` - Params: - `nickname` or `id` - Response: - On failure: `Not found` - 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 -- 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 + - *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 -## `/api/pleroma/admin/relay` +## `POST /api/pleroma/admin/relay` ### Follow a Relay -- Methods: `POST` - Params: - `relay_url` - Response: - On success: URL of the followed relay +## `DELETE /api/pleroma/admin/relay` + ### Unfollow a Relay -- Methods: `DELETE` - Params: - `relay_url` - Response: @@ -297,11 +317,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Response: - On success: JSON array of relays -## `/api/pleroma/admin/users/invite_token` +## `POST /api/pleroma/admin/users/invite_token` ### Create an account registration invite token -- Methods: `POST` - Params: - *optional* `max_use` (integer) - *optional* `expires_at` (date string e.g. "2019-04-07") @@ -319,11 +338,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 -- Methods: `GET` - Params: none - Response: @@ -345,11 +363,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 -- Methods: `POST` - Params: - `token` - Response: @@ -367,21 +384,32 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` - -## `/api/pleroma/admin/users/email_invite` +## `POST /api/pleroma/admin/users/email_invite` ### Sends registration invite via email -- Methods: `POST` - Params: - `email` - `name`, optional -## `/api/pleroma/admin/users/:nickname/password_reset` +- Response: + - On success: `204`, empty response + - On failure: + - 400 Bad Request, JSON: + + ```json + [ + { + "error": "Appropriate error message here" + } + ] + ``` + +## `GET /api/pleroma/admin/users/:nickname/password_reset` ### Get a password reset token for a given nickname -- Methods: `GET` + - Params: none - Response: @@ -392,18 +420,103 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` - -## `/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 -- Methods: `PATCH` -- Params: none +- Params: + - `nicknames` - Response: none (code `204`) -## `/api/pleroma/admin/reports` +## PUT `/api/pleroma/admin/users/disable_mfa` + +### Disable mfa for user's account. + +- Params: + - `nickname` +- Response: User’s nickname + +## `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 -- Method `GET` + - Params: - *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved` - *optional* `limit`: **integer** the number of records to retrieve @@ -418,7 +531,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret ```json { - "total" : 1, + "totalReports" : 1, "reports": [ { "account": { @@ -560,9 +673,34 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `/api/pleroma/admin/reports/:id` +## `GET /api/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) + +```json + "reports": [ + { + "date": "2019-10-07T12:31:39.615149Z", + "account": { ... }, + "status": { ... }, + "actors": [{ ... }, { ... }], + "reports": [{ ... }] + } + ] +``` + +## `GET /api/pleroma/admin/reports/:id` + ### Get an individual report -- Method `GET` + - Params: - `id` - Response: @@ -571,94 +709,76 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - 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` +## `PATCH /api/pleroma/admin/reports` + +### Change the state of one or multiple reports + - 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: - On failure: - - 400 Bad Request `"Unsupported state"` - - 403 Forbidden `{"error": "error_msg"}` - - 404 Not Found `"Not found"` - - On success: JSON, Report object (see above) + - 400 Bad Request, JSON: + + ```json + [ + { + `id`, // report id + `error` // error message + } + ] + ``` + + - On success: `204`, empty response + +## `POST /api/pleroma/admin/reports/:id/notes` + +### Create report note -## `/api/pleroma/admin/reports/:id/respond` -### Respond to a report -- Method `POST` - 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 + +## `GET /api/pleroma/admin/statuses/:id` + +### Show status by id + +- Params: + - `id`: required, status id +- Response: + - On failure: + - 404 Not Found `"Not Found"` + - On success: JSON, Mastodon Status entity + +## `PUT /api/pleroma/admin/statuses/:id` -## `/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` @@ -670,9 +790,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - 404 Not Found `"Not found"` - On success: JSON, Mastodon Status entity -## `/api/pleroma/admin/statuses/:id` +## `DELETE /api/pleroma/admin/statuses/:id` + ### Delete an individual reported status -- Method `DELETE` + - Params: - `id` - Response: @@ -681,89 +802,170 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - 404 Not Found `"Not found"` - On success: 200 OK `{}` +## `GET /api/pleroma/admin/restart` + +### Restarts pleroma application + +**Only works when configuration from database is enabled.** -## `/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: + - On failure: + - 400 Bad Request `"To use this endpoint you need to enable configuration from database."` ```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` +## `GET /api/pleroma/admin/need_reboot` + +### Returns the flag whether the pleroma should be restarted + - Params: none - Response: - + - `need_reboot` - boolean ```json -{} +{ + "need_reboot": false +} ``` -## `/api/pleroma/admin/config` -### List config settings -List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. -- Method `GET` -- Params: none +## `GET /api/pleroma/admin/config` + +### Get list of merged default settings with saved in database. + +*If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.* + +**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 } ``` -## `/api/pleroma/admin/config` +## `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 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: + +*If `need_reboot` is `true`, instance must be restarted, so reboot time settings can take effect.* + +**Only works when configuration from database is enabled.** + +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` - -- 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) +- 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} ] +``` + +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} + ] +``` -- Request (example): +*Settings without explicit key must be sended in separate config object params.* +```elixir +config :quack, + level: :debug, + meta: [:all], + ... +``` +```json +{ + "configs": [ + {"group": ":quack", "key": ":level", "value": ":debug"}, + {"group": ":quack", "key": ":meta", "value": [":all"]}, + ... + ] +} +``` +- Request: ```json { - configs: [ + "configs": [ { - "group": "pleroma", + "group": ":pleroma", "key": "Pleroma.Upload", "value": [ {"tuple": [":uploader", "Pleroma.Uploaders.Local"]}, @@ -773,7 +975,7 @@ Compile time settings (need instance reboot): {"tuple": [":proxy_opts", [ {"tuple": [":redirect_on_failure", false]}, {"tuple": [":max_body_length", 1048576]}, - {"tuple": [":http": [ + {"tuple": [":http", [ {"tuple": [":follow_redirect", true]}, {"tuple": [":pool", ":upload"]}, ]]} @@ -789,22 +991,58 @@ Compile time settings (need instance reboot): ``` - 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 } ``` -## `/api/pleroma/admin/moderation_log` +## ` 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` + ### Get moderation log -- Method `GET` + - Params: - *optional* `page`: **integer** page number - *optional* `page_size`: **integer** number of log entries per page (default is `50`) @@ -831,8 +1069,143 @@ Compile time settings (need instance reboot): ``` ## `POST /api/pleroma/admin/reload_emoji` + ### Reload the instance's custom emoji -* Method `POST` -* Authentication: required -* Params: None -* Response: JSON, "ok" and 200 status + +- 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 + } +} +``` + +## `GET /api/pleroma/admin/oauth_app` + +### List OAuth app + +- Params: + - *optional* `name` + - *optional* `client_id` + - *optional* `page` + - *optional* `page_size` + - *optional* `trusted` + +- Response: + +```json +{ + "apps": [ + { + "id": 1, + "name": "App name", + "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk", + "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY", + "redirect_uri": "https://example.com/oauth-callback", + "website": "https://example.com", + "trusted": true + } + ], + "count": 17, + "page_size": 50 +} +``` + + +## `POST /api/pleroma/admin/oauth_app` + +### Create OAuth App + +- Params: + - `name` + - `redirect_uris` + - `scopes` + - *optional* `website` + - *optional* `trusted` + +- Response: + +```json +{ + "id": 1, + "name": "App name", + "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk", + "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY", + "redirect_uri": "https://example.com/oauth-callback", + "website": "https://example.com", + "trusted": true +} +``` + +- On failure: +```json +{ + "redirect_uris": "can't be blank", + "name": "can't be blank" +} +``` + +## `PATCH /api/pleroma/admin/oauth_app/:id` + +### Update OAuth App + +- Params: + - *optional* `name` + - *optional* `redirect_uris` + - *optional* `scopes` + - *optional* `website` + - *optional* `trusted` + +- Response: + +```json +{ + "id": 1, + "name": "App name", + "client_id": "yHoDSiWYp5mPV6AfsaVOWjdOyt5PhWRiafi6MRd1lSk", + "client_secret": "nLmis486Vqrv2o65eM9mLQx_m_4gH-Q6PcDpGIMl6FY", + "redirect_uri": "https://example.com/oauth-callback", + "website": "https://example.com", + "trusted": true +} +``` + +## `DELETE /api/pleroma/admin/oauth_app/:id` + +### Delete OAuth App + +- Params: None + +- Response: + - On success: `204`, empty response + - On failure: + - 400 Bad Request `"Invalid parameters"` when `status` is missing
\ No newline at end of file diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md index aca0f5e0e..6d37d9008 100644 --- a/docs/API/differences_in_mastoapi_responses.md +++ b/docs/API/differences_in_mastoapi_responses.md @@ -4,7 +4,7 @@ A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma ## Flake IDs -Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mastodon's ids they are sortable strings +Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mastodon's ids they are lexically sortable strings ## Attachment cap @@ -14,6 +14,7 @@ Some apps operate under the assumption that no more than 4 attachments can be re Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users. Adding the parameter `exclude_visibilities` to the timeline queries will exclude the statuses with the given visibilities. The parameter accepts an array of visibility types (`public`, `unlisted`, `private`, `direct`), e.g., `exclude_visibilities[]=direct&exclude_visibilities[]=private`. +Adding the parameter `reply_visibility` to the public and home timelines queries will filter replies. Possible values: without parameter (default) shows all replies, `following` - replies directed to you or users you follow, `self` - replies directed to you. ## Statuses @@ -29,6 +30,7 @@ Has these additional fields under the `pleroma` object: - `spoiler_text`: a map consisting of alternate representations of the `spoiler_text` property with the key being it's mimetype. Currently the only alternate representation supported is `text/plain` - `expires_at`: a datetime (iso8601) that states when the post will expire (be deleted automatically), or empty if the post won't expire - `thread_muted`: true if the thread the post belongs to is muted +- `emoji_reactions`: A list with emoji / reaction maps. The format is `{name: "☕", count: 1, me: true}`. Contains no information about the reacting users, for that use the `/statuses/:id/reactions` endpoint. ## Attachments @@ -46,7 +48,7 @@ The `id` parameter can also be the `nickname` of the user. This only works in th Has these additional fields under the `pleroma` object: - `tags`: Lists an array of tags for the user -- `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/api/entities/#relationship +- `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/entities/relationship/ - `is_moderator`: boolean, nullable, true if user is a moderator - `is_admin`: boolean, nullable, true if user is an admin - `confirmation_pending`: boolean, true if a new user account is waiting on email confirmation to be activated @@ -57,7 +59,9 @@ Has these additional fields under the `pleroma` object: - `settings_store`: A generic map of settings for frontends. Opaque to the backend. Only returned in `verify_credentials` and `update_credentials` - `chat_token`: The token needed for Pleroma chat. Only returned in `verify_credentials` - `deactivated`: boolean, true when the user is deactivated +- `allow_following_move`: boolean, true when the user allows automatically follow moved following accounts - `unread_conversation_count`: The count of unread conversations. Only returned to the account owner. +- `unread_notifications_count`: The count of unread notifications. Only returned to the account owner. ### Source @@ -65,6 +69,8 @@ Has these additional fields under the `pleroma` object: - `show_role`: boolean, nullable, true when the user wants his role (e.g admin, moderator) to be shown - `no_rich_text` - boolean, nullable, true when html tags are stripped from all statuses requested from the API +- `discoverable`: boolean, true when the user allows discovery of the account in search results and other services. +- `actor_type`: string, the type of this account. ## Conversations @@ -72,12 +78,21 @@ Has an additional field under the `pleroma` object: - `recipients`: The list of the recipients of this Conversation. These will be addressed when replying to this conversation. +## GET `/api/v1/conversations` + +Accepts additional parameters: + +- `recipients`: Only return conversations with the given recipients (a list of user ids). Usage example: `GET /api/v1/conversations?recipients[]=1&recipients[]=2` + ## Account Search Behavior has changed: - `/api/v1/accounts/search`: Does not require authentication +## Search (global) + +Unlisted posts are available in search results, they are considered to be public posts that shouldn't be shown in local/federated timeline. ## Notifications @@ -85,11 +100,38 @@ Has these additional fields under the `pleroma` object: - `is_seen`: true if the notification was read by the user +### Move Notification + +The `type` value is `move`. Has an additional field: + +- `target`: new account + +### EmojiReact Notification + +The `type` value is `pleroma:emoji_reaction`. Has these fields: + +- `emoji`: The used emoji +- `account`: The account of the user who reacted +- `status`: The status that was reacted on + ## GET `/api/v1/notifications` Accepts additional parameters: - `exclude_visibilities`: will exclude the notifications for activities with the given visibilities. The parameter accepts an array of visibility types (`public`, `unlisted`, `private`, `direct`). Usage example: `GET /api/v1/notifications?exclude_visibilities[]=direct&exclude_visibilities[]=private`. +- `include_types`: will include the notifications for activities with the given types. The parameter accepts an array of types (`mention`, `follow`, `reblog`, `favourite`, `move`, `pleroma:emoji_reaction`). Usage example: `GET /api/v1/notifications?include_types[]=mention&include_types[]=reblog`. + +## DELETE `/api/v1/notifications/destroy_multiple` + +An endpoint to delete multiple statuses by IDs. + +Required parameters: + +- `ids`: array of activity ids + +Usage example: `DELETE /api/v1/notifications/destroy_multiple/?ids[]=1&ids[]=2`. + +Returns on success: 200 OK `{}` ## POST `/api/v1/statuses` @@ -130,9 +172,13 @@ Additional parameters can be added to the JSON body/Form data: - `default_scope` - the scope returned under `privacy` key in Source subentity - `pleroma_settings_store` - Opaque user settings to be saved on the backend. - `skip_thread_containment` - if true, skip filtering out broken threads +- `allow_following_move` - if true, allows automatically follow moved following accounts - `pleroma_background_image` - sets the background image of the user. +- `discoverable` - if true, discovery of this account in search results and other services is allowed. +- `actor_type` - the type of this account. ### Pleroma Settings Store + Pleroma has mechanism that allows frontends to save blobs of json for each user on the backend. This can be used to save frontend-specific settings for a user that the backend does not need to know about. The parameter should have a form of `{frontend_name: {...}}`, with `frontend_name` identifying your type of client, e.g. `pleroma_fe`. It will overwrite everything under this property, but will not overwrite other frontend's settings. @@ -141,17 +187,41 @@ This information is returned in the `verify_credentials` endpoint. ## Authentication -*Pleroma supports refreshing tokens. +*Pleroma supports refreshing tokens.* `POST /oauth/token` -Post here request with grant_type=refresh_token to obtain new access token. Returns an access token. + +Post here request with `grant_type=refresh_token` to obtain new access token. Returns an access token. ## Account Registration + `POST /api/v1/accounts` -Has theses additionnal parameters (which are the same as in Pleroma-API): - * `fullname`: optional - * `bio`: optional - * `captcha_solution`: optional, contains provider-specific captcha solution, - * `captcha_token`: optional, contains provider-specific captcha token - * `token`: invite token required when the registerations aren't public. +Has theses additional parameters (which are the same as in Pleroma-API): + +- `fullname`: optional +- `bio`: optional +- `captcha_solution`: optional, contains provider-specific captcha solution, +- `captcha_token`: optional, contains provider-specific captcha token +- `captcha_answer_data`: optional, contains provider-specific captcha data +- `token`: invite token required when the registrations aren't public. + +## Instance + +`GET /api/v1/instance` has additional fields + +- `max_toot_chars`: The maximum characters per post +- `poll_limits`: The limits of polls +- `upload_limit`: The maximum upload file size +- `avatar_upload_limit`: The same for avatars +- `background_upload_limit`: The same for backgrounds +- `banner_upload_limit`: The same for banners +- `pleroma.metadata.features`: A list of supported features +- `pleroma.metadata.federation`: The federation restrictions of this instance +- `vapid_public_key`: The public key needed for push messages + +## Markers + +Has these additional fields under the `pleroma` object: + +- `unread_count`: contains number unread notifications diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md index 6c326dc9b..5895613a3 100644 --- a/docs/API/pleroma_api.md +++ b/docs/API/pleroma_api.md @@ -70,60 +70,49 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi * Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise * Example response: `{"error": "Invalid password."}` -## `/api/account/register` -### Register a new user -* Method `POST` -* Authentication: not required +## `/api/pleroma/accounts/mfa` +#### Gets current MFA settings +* method: `GET` +* Authentication: required +* OAuth scope: `read:security` +* Response: JSON. Returns `{"enabled": "false", "totp": false }` + +## `/api/pleroma/accounts/mfa/setup/totp` +#### Pre-setup the MFA/TOTP method +* method: `GET` +* Authentication: required +* OAuth scope: `write:security` +* Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]" }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}` + +## `/api/pleroma/accounts/mfa/confirm/totp` +#### Confirms & enables MFA/TOTP support for user account. +* method: `POST` +* Authentication: required +* OAuth scope: `write:security` * Params: - * `nickname` - * `fullname` - * `bio` - * `email` - * `password` - * `confirm` - * `captcha_solution`: optional, contains provider-specific captcha solution, - * `captcha_token`: optional, contains provider-specific captcha token - * `token`: invite token required when the registrations aren't public. -* Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}` -* Example response: -```json -{ - "background_image": null, - "cover_photo": "https://pleroma.soykaf.com/images/banner.png", - "created_at": "Tue Dec 18 16:55:56 +0000 2018", - "default_scope": "public", - "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.", - "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.", - "favourites_count": 0, - "fields": [], - "followers_count": 0, - "following": false, - "follows_you": false, - "friends_count": 0, - "id": 6, - "is_local": true, - "locked": false, - "name": "lain", - "name_html": "lain", - "no_rich_text": false, - "pleroma": { - "tags": [] - }, - "profile_image_url": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png", - "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png", - "rights": { - "delete_others_notice": false - }, - "screen_name": "lain", - "statuses_count": 0, - "statusnet_blocking": false, - "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain" -} -``` + * `password`: user's password + * `code`: token from TOTP App +* Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise + + +## `/api/pleroma/accounts/mfa/totp` +#### Disables MFA/TOTP method for user account. +* method: `DELETE` +* Authentication: required +* OAuth scope: `write:security` +* Params: + * `password`: user's password +* Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise +* Example response: `{"error": "Invalid password."}` + +## `/api/pleroma/accounts/mfa/backup_codes` +#### Generstes backup codes MFA for user account. +* method: `GET` +* Authentication: required +* OAuth scope: `write:security` +* Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}` -## `/api/pleroma/admin/`… +## `/api/pleroma/admin/` See [Admin-API](admin_api.md) ## `/api/v1/pleroma/notifications/read` @@ -302,6 +291,7 @@ See [Admin-API](admin_api.md) * `follows`: BOOLEAN field, receives notifications from people the user follows * `remote`: BOOLEAN field, receives notifications from people on remote instances * `local`: BOOLEAN field, receives notifications from people on the local instance + * `privacy_option`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification. * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}` ## `/api/pleroma/healthcheck` @@ -340,10 +330,11 @@ Pleroma Conversations have the same general structure that Mastodon Conversation 2. Pleroma Conversations statuses can be requested by Conversation id. 3. Pleroma Conversations can be replied to. -Conversations have the additional field "recipients" under the "pleroma" key. This holds a list of all the accounts that will receive a message in this conversation. +Conversations have the additional field `recipients` under the `pleroma` key. This holds a list of all the accounts that will receive a message in this conversation. The status posting endpoint takes an additional parameter, `in_reply_to_conversation_id`, which, when set, will set the visiblity to direct and address only the people who are the recipients of that Conversation. +⚠ Conversation IDs can be found in direct messages with the `pleroma.direct_conversation_id` key, do not confuse it with `pleroma.conversation_id`. ## `GET /api/v1/pleroma/conversations/:id/statuses` ### Timeline for a given conversation @@ -374,20 +365,54 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa * Params: None * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy). -## `GET /api/pleroma/emoji/packs` -### Lists the custom emoji packs on the server +## `GET /api/pleroma/emoji/packs/import` +### Imports packs from filesystem * Method `GET` -* Authentication: not required +* Authentication: required * Params: None -* Response: JSON, "ok" and 200 status and the JSON hashmap of "pack name" to "pack contents" +* Response: JSON, returns a list of imported packs. -## `PUT /api/pleroma/emoji/packs/:name` -### Creates an empty custom emoji pack -* Method `PUT` +## `GET /api/pleroma/emoji/packs/remote` +### Make request to another instance for packs list +* Method `GET` +* Authentication: required +* Params: + * `url`: url of the instance to get packs from +* Response: JSON with the pack list, hashmap with pack name and pack contents + +## `POST /api/pleroma/emoji/packs/download` +### Download pack from another instance +* Method `POST` +* Authentication: required +* Params: + * `url`: url of the instance to download from + * `name`: pack to download from that instance + * `as`: (*optional*) name how to save pack +* Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were + errors downloading the pack + +## `POST /api/pleroma/emoji/packs/:name` +### Creates an empty pack +* Method `POST` * Authentication: required * Params: None * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists +## `PATCH /api/pleroma/emoji/packs/:name` +### Updates (replaces) pack metadata +* Method `PATCH` +* Authentication: required +* Params: + * `metadata`: metadata to replace the old one + * `license`: Pack license + * `homepage`: Pack home page url + * `description`: Pack description + * `fallback-src`: Fallback url to download pack from + * `fallback-src-sha256`: SHA256 encoded for fallback pack archive + * `share-files`: is pack allowed for sharing (boolean) +* Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a + problem with the new metadata (the error is specified in the "error" part of the response JSON) + ## `DELETE /api/pleroma/emoji/packs/:name` ### Delete a custom emoji pack * Method `DELETE` @@ -395,53 +420,51 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa * Params: None * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack -## `POST /api/pleroma/emoji/packs/:name/update_file` -### Update a file in a custom emoji pack +## `POST /api/pleroma/emoji/packs/:name/files` +### Add new file to the pack * Method `POST` * Authentication: required * Params: - * if the `action` is `add`, adds an emoji named `shortcode` to the pack `pack_name`, - that means that the emoji file needs to be uploaded with the request - (thus requiring it to be a multipart request) and be named `file`. - There can also be an optional `filename` that will be the new emoji file name - (if it's not there, the name will be taken from the uploaded file). - * if the `action` is `update`, changes emoji shortcode - (from `shortcode` to `new_shortcode` or moves the file (from the current filename to `new_filename`) - * if the `action` is `remove`, removes the emoji named `shortcode` and it's associated file -* Response: JSON, updated "files" section of the pack and 200 status, 409 if the trying to use a shortcode - that is already taken, 400 if there was an error with the shortcode, filename or file (additional info - in the "error" part of the response JSON) - -## `POST /api/pleroma/emoji/packs/:name/update_metadata` -### Updates (replaces) pack metadata -* Method `POST` -* Authentication: required -* Params: - * `new_data`: new metadata to replace the old one -* Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a - problem with the new metadata (the error is specified in the "error" part of the response JSON) + * `file`: file needs to be uploaded with the multipart request or link to remote file. + * `shortcode`: (*optional*) shortcode for new emoji, must be uniq for all emoji. If not sended, shortcode will be taken from original filename. + * `filename`: (*optional*) new emoji file name. If not specified will be taken from original filename. +* Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message. -## `POST /api/pleroma/emoji/packs/download_from` -### Requests the instance to download the pack from another instance -* Method `POST` +## `PATCH /api/pleroma/emoji/packs/:name/files` +### Update emoji file from pack +* Method `PATCH` * Authentication: required * Params: - * `instance_address`: the address of the instance to download from - * `pack_name`: the pack to download from that instance -* Response: JSON, "ok" and 200 status if the pack was downloaded, or 500 if there were - errors downloading the pack - -## `POST /api/pleroma/emoji/packs/list_from` -### Requests the instance to list the packs from another instance -* Method `POST` + * `shortcode`: emoji file shortcode + * `new_shortcode`: new emoji file shortcode + * `new_filename`: new filename for emoji file + * `force`: (*optional*) with true value to overwrite existing emoji with new shortcode +* Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message. + +## `DELETE /api/pleroma/emoji/packs/:name/files` +### Delete emoji file from pack +* Method `DELETE` * Authentication: required * Params: - * `instance_address`: the address of the instance to download from -* Response: JSON with the pack list, same as if the request was made to that instance's - list endpoint directly + 200 status + * `shortcode`: emoji file shortcode +* Response: JSON, list with updated files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message. + +## `GET /api/pleroma/emoji/packs` +### Lists local custom emoji packs +* Method `GET` +* Authentication: not required +* Params: None +* Response: JSON, "ok" and 200 status and the JSON hashmap of pack name to pack contents + +## `GET /api/pleroma/emoji/packs/:name` +### Get pack.json for the pack +* Method `GET` +* Authentication: not required +* Params: None +* Response: JSON, pack json with `files` and `pack` keys with 200 status or 404 if the pack does not exist -## `GET /api/pleroma/emoji/packs/:name/download_shared` -### Requests a local pack from the instance +## `GET /api/pleroma/emoji/packs/:name/archive` +### Requests a local pack archive from the instance * Method `GET` * Authentication: not required * Params: None @@ -479,3 +502,48 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa * `artist`: the artist of the media playing [optional] * `length`: the length of the media playing [optional] * Response: the newly created media metadata entity representing the Listen activity + +# Emoji Reactions + +Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character. To detect the presence of this feature, you can check `pleroma_emoji_reactions` entry in the features list of nodeinfo. + +## `PUT /api/v1/pleroma/statuses/:id/reactions/:emoji` +### React to a post with a unicode emoji +* Method: `PUT` +* Authentication: required +* Params: `emoji`: A single character unicode emoji +* Response: JSON, the status. + +## `DELETE /api/v1/pleroma/statuses/:id/reactions/:emoji` +### Remove a reaction to a post with a unicode emoji +* Method: `DELETE` +* Authentication: required +* Params: `emoji`: A single character unicode emoji +* Response: JSON, the status. + +## `GET /api/v1/pleroma/statuses/:id/reactions` +### Get an object of emoji to account mappings with accounts that reacted to the post +* Method: `GET` +* Authentication: optional +* Params: None +* Response: JSON, a list of emoji/account list tuples, sorted by emoji insertion date, in ascending order, e.g, the first emoji in the list is the oldest. +* Example Response: +```json +[ + {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]}, + {"name": "☕", "count": 1, "me": false, "accounts": [{"id" => "abc..."}]} +] +``` + +## `GET /api/v1/pleroma/statuses/:id/reactions/:emoji` +### Get an object of emoji to account mappings with accounts that reacted to the post for a specific emoji` +* Method: `GET` +* Authentication: optional +* Params: None +* Response: JSON, a list of emoji/account list tuples +* Example Response: +```json +[ + {"name": "😀", "count": 2, "me": true, "accounts": [{"id" => "xyz.."...}, {"id" => "zyx..."}]} +] +``` |