From 38926a063a39c4d4387049f5d364f72a9f8bd2de Mon Sep 17 00:00:00 2001 From: Egor Kislitsyn Date: Mon, 15 Apr 2019 16:39:42 +0700 Subject: add `/api/pleroma/disable_account` to `docs/api/pleroma_api.md` --- docs/api/pleroma_api.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/api') diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md index dbe250300..b9622f586 100644 --- a/docs/api/pleroma_api.md +++ b/docs/api/pleroma_api.md @@ -61,6 +61,15 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise * Example response: `{"error": "Invalid password."}` +## `/api/pleroma/disable_account` +### Disable an account +* Method `POST` +* Authentication: required +* Params: + * `password`: user's password +* 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` -- cgit v1.2.3 From 1040caf096347b638b9fda5b23fcccde87b32ede Mon Sep 17 00:00:00 2001 From: Maksim Date: Mon, 6 May 2019 17:51:03 +0000 Subject: fix format Modified-by: Maksim Pechnikov --- docs/api/differences_in_mastoapi_responses.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/api') diff --git a/docs/api/differences_in_mastoapi_responses.md b/docs/api/differences_in_mastoapi_responses.md index 1350ace43..d3ba41b6a 100644 --- a/docs/api/differences_in_mastoapi_responses.md +++ b/docs/api/differences_in_mastoapi_responses.md @@ -1,6 +1,6 @@ # Differences in Mastodon API responses from vanilla Mastodon -A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` +A Pleroma instance can be identified by " (compatible; Pleroma )" present in `version` field in response from `/api/v1/instance` ## Flake IDs @@ -80,3 +80,10 @@ Additional parameters can be added to the JSON body/Form data: - `hide_favorites` - if true, user's favorites timeline will be hidden - `show_role` - if true, user's role (e.g admin, moderator) will be exposed to anyone in the API - `default_scope` - the scope returned under `privacy` key in Source subentity + +## Authentication + +*Pleroma supports refreshing tokens. + +`POST /oauth/token` +Post here request with grant_type=refresh_token to obtain new access token. Returns an access token. -- cgit v1.2.3 From bfeb33e951c8997f33a0242fe69b8e669e3afe07 Mon Sep 17 00:00:00 2001 From: Alexander Strizhakov Date: Wed, 8 May 2019 14:34:36 +0000 Subject: Merge develop Merge conflict in lib/pleroma/activity.ex --- docs/api/admin_api.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 8befa8ea0..2657d1243 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -8,15 +8,20 @@ Authentication is required and the user must be an admin. - Method `GET` - Query Params: - - *optional* `query`: **string** search term + - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain) - *optional* `filters`: **string** comma-separated string of filters: - `local`: only local users - `external`: only external users - `active`: only active users - `deactivated`: only deactivated users + - `is_admin`: users with admin role + - `is_moderator`: users with moderator role - *optional* `page`: **integer** page number - *optional* `page_size`: **integer** number of users per page (default is `50`) -- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10` + - *optional* `tags`: **[string]** tags list + - *optional* `name`: **string** user display name + - *optional* `email`: **string** user email +- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com` - Response: ```JSON -- cgit v1.2.3 From f01f995816d86999d5cbf261605887b3a3b313ac Mon Sep 17 00:00:00 2001 From: Sachin Joshi Date: Sat, 11 May 2019 14:17:04 +0545 Subject: make url uniform in admin api --- docs/api/admin_api.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'docs/api') diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 2657d1243..75fa2ee83 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -45,7 +45,7 @@ Authentication is required and the user must be an admin. } ``` -## `/api/pleroma/admin/user` +## `/api/pleroma/admin/users` ### Remove a user @@ -63,7 +63,7 @@ Authentication is required and the user must be an admin. - `password` - Response: User’s nickname -## `/api/pleroma/admin/user/follow` +## `/api/pleroma/admin/users/follow` ### Make a user follow another user - Methods: `POST` @@ -73,7 +73,7 @@ Authentication is required and the user must be an admin. - Response: - "ok" -## `/api/pleroma/admin/user/unfollow` +## `/api/pleroma/admin/users/unfollow` ### Make a user unfollow another user - Methods: `POST` @@ -116,7 +116,7 @@ Authentication is required and the user must be an admin. - `nickname` - `tags` -## `/api/pleroma/admin/permission_group/:nickname` +## `/api/pleroma/admin/users/:nickname/permission_group` ### Get user user permission groups membership @@ -131,7 +131,7 @@ Authentication is required and the user must be an admin. } ``` -## `/api/pleroma/admin/permission_group/:nickname/:permission_group` +## `/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. @@ -165,7 +165,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On success: JSON of the `user.info` - Note: An admin cannot revoke their own admin status. -## `/api/pleroma/admin/activation_status/:nickname` +## `/api/pleroma/admin/users/:nickname/activation_status` ### Active or deactivate a user @@ -203,7 +203,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Response: - On success: URL of the unfollowed relay -## `/api/pleroma/admin/invite_token` +## `/api/pleroma/admin/users/invite_token` ### Get an account registration invite token @@ -215,7 +215,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret ] - Response: invite token (base64 string) -## `/api/pleroma/admin/invites` +## `/api/pleroma/admin/users/invites` ### Get a list of generated invites @@ -241,7 +241,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `/api/pleroma/admin/revoke_invite` +## `/api/pleroma/admin/users/revoke_invite` ### Revoke invite by token @@ -264,7 +264,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret ``` -## `/api/pleroma/admin/email_invite` +## `/api/pleroma/admin/users/email_invite` ### Sends registration invite via email @@ -273,7 +273,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `email` - `name`, optional -## `/api/pleroma/admin/password_reset` +## `/api/pleroma/admin/users/:nickname/password_reset` ### Get a password reset token for a given nickname -- cgit v1.2.3 From a2be420f940fb8f181feeb9b0fb9759d433dcae1 Mon Sep 17 00:00:00 2001 From: Alexander Strizhakov Date: Mon, 13 May 2019 18:35:45 +0000 Subject: differences_in_mastoapi_responses.md: fullname & bio are optionnal [ci skip] --- docs/api/differences_in_mastoapi_responses.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/api') diff --git a/docs/api/differences_in_mastoapi_responses.md b/docs/api/differences_in_mastoapi_responses.md index d3ba41b6a..36b47608e 100644 --- a/docs/api/differences_in_mastoapi_responses.md +++ b/docs/api/differences_in_mastoapi_responses.md @@ -87,3 +87,13 @@ Additional parameters can be added to the JSON body/Form data: `POST /oauth/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. -- cgit v1.2.3 From 1d2923e5d0893b39f41ded77d24652029f6f12ec Mon Sep 17 00:00:00 2001 From: Angelina Filippova Date: Thu, 16 May 2019 01:36:26 +0300 Subject: Update tag/untag docs --- docs/api/admin_api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 75fa2ee83..8f79d7f24 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -106,14 +106,14 @@ Authentication is required and the user must be an admin. - Method: `PUT` - Params: - - `nickname` + - `nicknames` - `tags` ### Untag a list of users - Method: `DELETE` - Params: - - `nickname` + - `nicknames` - `tags` ## `/api/pleroma/admin/users/:nickname/permission_group` -- cgit v1.2.3 From 0641e685c166859fe2d5994bfcd069e0a8e62acf Mon Sep 17 00:00:00 2001 From: Angelina Filippova Date: Thu, 16 May 2019 01:46:43 +0300 Subject: Note that nicknames is an array --- docs/api/admin_api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 8f79d7f24..94fce9c6f 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -106,14 +106,14 @@ Authentication is required and the user must be an admin. - Method: `PUT` - Params: - - `nicknames` + - `nicknames` (array) - `tags` ### Untag a list of users - Method: `DELETE` - Params: - - `nicknames` + - `nicknames` (array) - `tags` ## `/api/pleroma/admin/users/:nickname/permission_group` -- cgit v1.2.3 From 107c83ab2b186c951dc27140908d414a202119d8 Mon Sep 17 00:00:00 2001 From: Angelina Filippova Date: Thu, 16 May 2019 01:48:53 +0300 Subject: Note that nicknames is an array --- docs/api/admin_api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 94fce9c6f..59578f8d1 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -107,14 +107,14 @@ Authentication is required and the user must be an admin. - Method: `PUT` - Params: - `nicknames` (array) - - `tags` + - `tags` (array) ### Untag a list of users - Method: `DELETE` - Params: - `nicknames` (array) - - `tags` + - `tags` (array) ## `/api/pleroma/admin/users/:nickname/permission_group` -- cgit v1.2.3 From e2b3a27204ca511a2e455a1151fdea36fdc0e53d Mon Sep 17 00:00:00 2001 From: Sergey Suprunenko Date: Thu, 16 May 2019 19:09:18 +0000 Subject: Add Reports to Admin API --- docs/api/admin_api.md | 289 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 283 insertions(+), 6 deletions(-) (limited to 'docs/api') diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 59578f8d1..b45c5e285 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, @@ -92,7 +92,7 @@ Authentication is required and the user must be an admin. - `nickname` - Response: User’s object -```JSON +```json { "deactivated": bool, "id": integer, @@ -124,7 +124,7 @@ Authentication is required and the user must be an admin. - Params: none - Response: -```JSON +```json { "is_moderator": bool, "is_admin": bool @@ -141,7 +141,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Params: none - Response: -```JSON +```json { "is_moderator": bool, "is_admin": bool @@ -223,7 +223,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Params: none - Response: -```JSON +```json { "invites": [ @@ -250,7 +250,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `token` - Response: -```JSON +```json { "id": integer, "token": string, @@ -280,3 +280,280 @@ 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 + }, + "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 + }, + "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 `{}` -- cgit v1.2.3 From 54e9cb5c2db580bc12441f3651fa87a7b976137d Mon Sep 17 00:00:00 2001 From: Sadposter Date: Mon, 20 May 2019 12:39:23 +0100 Subject: Add API endpoints for a custom user mascot --- docs/api/pleroma_api.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs/api') diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md index dd0b6ca73..4d99a2d2b 100644 --- a/docs/api/pleroma_api.md +++ b/docs/api/pleroma_api.md @@ -252,6 +252,45 @@ See [Admin-API](Admin-API.md) ] ``` +## `/api/v1/pleroma/mascot` +### Gets user mascot image +* Method `GET` +* Authentication: required + +* Response: JSON. Returns a mastodon media attachment entity. +* Example response: +```json +{ + "id": "abcdefg", + "url": "https://pleroma.example.org/media/abcdefg.png", + "type": "image", + "pleroma": { + "mime_type": "image/png" + } +} +``` + +### Updates user mascot image +* Method `PUT` +* Authentication: required +* Params: + * `image`: Multipart image +* Response: JSON. Returns a mastodon media attachment entity + when successful, otherwise returns HTTP 415 `{"error": "error_msg"}` +* Example response: +```json +{ + "id": "abcdefg", + "url": "https://pleroma.example.org/media/abcdefg.png", + "type": "image", + "pleroma": { + "mime_type": "image/png" + } +} +``` +* Note: Behaves exactly the same as `POST /api/v1/upload`. + Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`. + ## `/api/pleroma/notification_settings` ### Updates user notification settings * Method `PUT` -- cgit v1.2.3 From 5d3ece2861b619c101d6860fbc1a80bfd8630ba7 Mon Sep 17 00:00:00 2001 From: "Haelwenn (lanodan) Monnier" Date: Sat, 1 Jun 2019 01:42:46 +0200 Subject: Remove now useless flavours switching --- docs/api/pleroma_api.md | 14 -------------- 1 file changed, 14 deletions(-) (limited to 'docs/api') diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md index 4d99a2d2b..edc62727a 100644 --- a/docs/api/pleroma_api.md +++ b/docs/api/pleroma_api.md @@ -126,20 +126,6 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi ## `/api/pleroma/admin/`… See [Admin-API](Admin-API.md) -## `/api/v1/pleroma/flavour/:flavour` -* Method `POST` -* Authentication: required -* Response: JSON string. Returns the user flavour or the default one on success, otherwise returns `{"error": "error_msg"}` -* Example response: "glitch" -* Note: This is intended to be used only by mastofe - -## `/api/v1/pleroma/flavour` -* Method `GET` -* Authentication: required -* Response: JSON string. Returns the user flavour or the default one. -* Example response: "glitch" -* Note: This is intended to be used only by mastofe - ## `/api/pleroma/notifications/read` ### Mark a single notification as read * Method `POST` -- cgit v1.2.3