Merge branch 'openapi/admin/status' into 'develop'

[akkoma] / docs / API / pleroma_api.md

diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md
index 65d22980b653094f0afd216c95850ab68f0ec9bd..70d4755b7ce2362bd6357529ae42a122a447bfbb 100644 (file)
--- a/docs/API/pleroma_api.md
+++ b/docs/API/pleroma_api.md
@@ -70,7 +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/pleroma/admin/`…
+## `/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:
+    * `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/`
 See [Admin-API](admin_api.md)
 
 ## `/api/v1/pleroma/notifications/read`
@@ -223,7 +265,7 @@ See [Admin-API](admin_api.md)
 * Method `PUT`
 * Authentication: required
 * Params:
-    * `image`: Multipart image
+    * `file`: Multipart image
 * Response: JSON. Returns a mastodon media attachment entity
   when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
 * Example response:
@@ -316,7 +358,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
     * `recipients`: A list of ids of users that should receive posts to this conversation. This will replace the current list of recipients, so submit the full list. The owner of owner of the conversation will always be part of the set of recipients, though.
 * Response: JSON, statuses (200 - healthy, 503 unhealthy)
 
-## `GET /api/v1/pleroma/conversations/read`
+## `POST /api/v1/pleroma/conversations/read`
 ### Marks all user's conversations as read.
 * Method `POST`
 * Authentication: required
@@ -345,6 +387,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
 * 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
 
@@ -357,10 +400,16 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
 
 ## `PATCH /api/pleroma/emoji/packs/:name`
 ### Updates (replaces) pack metadata
-* Method `POST`
+* 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)
 
@@ -376,10 +425,10 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
 * Method `POST`
 * Authentication: required
 * Params:
-  * `file`: uploaded file 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.
+  * `file`: file needs to be uploaded with the multipart request or link to remote file.
+  * `shortcode`: (*optional*) shortcode for new emoji, must be unique 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 (hasmap -> shortcode => filename) with status 200, either error status with error message.
+* Response: JSON, list of files for updated pack (hashmap -> shortcode => filename) with status 200, either error status with error message.
 
 ## `PATCH /api/pleroma/emoji/packs/:name/files`
 ### Update emoji file from pack
@@ -390,7 +439,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
   * `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 (hasmap -> shortcode => filename) with status 200, either error status with error message.
+* 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
@@ -398,7 +447,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
 * Authentication: required
 * Params:
   * `shortcode`: emoji file shortcode
-* Response: JSON, list with updated files for updated pack (hasmap -> shortcode => filename) with status 200, either error status with error message.
+* 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
@@ -415,7 +464,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
 * 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/archive`
-### Requests a local pack from the instance
+### Requests a local pack archive from the instance
 * Method `GET`
 * Authentication: not required
 * Params: None
@@ -487,7 +536,7 @@ Emoji reactions work a lot like favourites do. They make it possible to react to
 ```
 
 ## `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`
+### 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