Merge branch 'api-docs-fixes' into 'develop'

Docs: fix various Pleroma API endpoints paths, fix MFA response

See merge request pleroma/pleroma!3596
This commit is contained in:
Alex Gleason 2022-01-07 20:29:28 +00:00
commit 2451d65bd8

View file

@ -37,7 +37,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
``` ```
* Note: Same data as Mastodon APIs `/api/v1/custom_emojis` but in a different format * Note: Same data as Mastodon APIs `/api/v1/custom_emojis` but in a different format
## `/api/v1/pleroma/follow_import` ## `/api/pleroma/follow_import`
### Imports your follows, for example from a Mastodon CSV file. ### Imports your follows, for example from a Mastodon CSV file.
* Method: `POST` * Method: `POST`
* Authentication: required * Authentication: required
@ -46,7 +46,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
* Response: HTTP 200 on success, 500 on error * Response: HTTP 200 on success, 500 on error
* Note: Users that can't be followed are silently skipped. * Note: Users that can't be followed are silently skipped.
## `/api/v1/pleroma/blocks_import` ## `/api/pleroma/blocks_import`
### Imports your blocks. ### Imports your blocks.
* Method: `POST` * Method: `POST`
* Authentication: required * Authentication: required
@ -54,7 +54,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
* `list`: STRING or FILE containing a whitespace-separated list of accounts to block * `list`: STRING or FILE containing a whitespace-separated list of accounts to block
* Response: HTTP 200 on success, 500 on error * Response: HTTP 200 on success, 500 on error
## `/api/v1/pleroma/mutes_import` ## `/api/pleroma/mutes_import`
### Imports your mutes. ### Imports your mutes.
* Method: `POST` * Method: `POST`
* Authentication: required * Authentication: required
@ -70,7 +70,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
* Response: Provider specific JSON, the only guaranteed parameter is `type` * Response: Provider specific JSON, the only guaranteed parameter is `type`
* Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint", "seconds_valid": 300}` * Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint", "seconds_valid": 300}`
## `/api/v1/pleroma/delete_account` ## `/api/pleroma/delete_account`
### Delete an account ### Delete an account
* Method `POST` * Method `POST`
* Authentication: required * Authentication: required
@ -79,7 +79,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
* Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise * Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise
* Example response: `{"error": "Invalid password."}` * Example response: `{"error": "Invalid password."}`
## `/api/v1/pleroma/disable_account` ## `/api/pleroma/disable_account`
### Disable an account ### Disable an account
* Method `POST` * Method `POST`
* Authentication: required * Authentication: required
@ -88,21 +88,22 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
* Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise * Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise
* Example response: `{"error": "Invalid password."}` * Example response: `{"error": "Invalid password."}`
## `/api/v1/pleroma/accounts/mfa` ## `/api/pleroma/accounts/mfa`
#### Gets current MFA settings #### Gets current MFA settings
* method: `GET` * method: `GET`
* Authentication: required * Authentication: required
* OAuth scope: `read:security` * OAuth scope: `read:security`
* Response: JSON. Returns `{"enabled": "false", "totp": false }` * Response: JSON. Returns `{"settings": {"enabled": "false", "totp": false }}`
* Note: `enabled` is whether multi-factor auth is enabled for the user in general, while `totp` is one type of MFA.
## `/api/v1/pleroma/accounts/mfa/setup/totp` ## `/api/pleroma/accounts/mfa/setup/totp`
#### Pre-setup the MFA/TOTP method #### Pre-setup the MFA/TOTP method
* method: `GET` * method: `GET`
* Authentication: required * Authentication: required
* OAuth scope: `write:security` * OAuth scope: `write:security`
* Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]" }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}` * Response: JSON. Returns `{"key": [secret_key], "provisioning_uri": "[qr code uri]" }` when successful, otherwise returns HTTP 422 `{"error": "error_msg"}`
## `/api/v1/pleroma/accounts/mfa/confirm/totp` ## `/api/pleroma/accounts/mfa/confirm/totp`
#### Confirms & enables MFA/TOTP support for user account. #### Confirms & enables MFA/TOTP support for user account.
* method: `POST` * method: `POST`
* Authentication: required * Authentication: required
@ -113,7 +114,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
* Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise * Response: JSON. Returns `{}` if the enable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
## `/api/v1/pleroma/accounts/mfa/totp` ## `/api/pleroma/accounts/mfa/totp`
#### Disables MFA/TOTP method for user account. #### Disables MFA/TOTP method for user account.
* method: `DELETE` * method: `DELETE`
* Authentication: required * Authentication: required
@ -123,7 +124,7 @@ The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/ap
* Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise * Response: JSON. Returns `{}` if the disable was successful, HTTP 422 `{"error": "[error message]"}` otherwise
* Example response: `{"error": "Invalid password."}` * Example response: `{"error": "Invalid password."}`
## `/api/v1/pleroma/accounts/mfa/backup_codes` ## `/api/pleroma/accounts/mfa/backup_codes`
#### Generstes backup codes MFA for user account. #### Generstes backup codes MFA for user account.
* method: `GET` * method: `GET`
* Authentication: required * Authentication: required
@ -331,7 +332,7 @@ See [Admin-API](admin_api.md)
} }
``` ```
## `/api/v1/pleroma/change_email` ## `/api/pleroma/change_email`
### Change account email ### Change account email
* Method `POST` * Method `POST`
* Authentication: required * Authentication: required