limepotato/akkoma
1
0
Fork 0
Code Pull requests Activity

Update the documentation to use make it use /api/v1/pleroma instead of /api/pleroma

Browse source
This commit is contained in:
eugenijm 2021-02-22 04:26:56 +03:00
parent c1d63bbd9a
commit c140cc7bf3
4 changed files with 113 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/configuration/cheatsheet.md
View file

@ -49,7 +49,7 @@ To add configuration to your config file, you can copy it from the base config.
* `attachment_links`: Set to true to enable automatically adding attachment link text to statuses. * `attachment_links`: Set to true to enable automatically adding attachment link text to statuses.
* `max_report_comment_size`: The maximum size of the report comment (Default: `1000`). * `max_report_comment_size`: The maximum size of the report comment (Default: `1000`).
* `safe_dm_mentions`: If set to true, only mentions at the beginning of a post will be used to address people in direct messages. This is to prevent accidental mentioning of people when talking about them (e.g. "@friend hey i really don't like @enemy"). Default: `false`. * `safe_dm_mentions`: If set to true, only mentions at the beginning of a post will be used to address people in direct messages. This is to prevent accidental mentioning of people when talking about them (e.g. "@friend hey i really don't like @enemy"). Default: `false`.
* `healthcheck`: If set to true, system data will be shown on ``/api/pleroma/healthcheck``. * `healthcheck`: If set to true, system data will be shown on ``/api/v1/pleroma/healthcheck``.
* `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database. * `remote_post_retention_days`: The default amount of days to retain remote posts when pruning the database.
* `user_bio_length`: A user bio maximum length (default: `5000`). * `user_bio_length`: A user bio maximum length (default: `5000`).
* `user_name_length`: A user name maximum length (default: `100`). * `user_name_length`: A user name maximum length (default: `100`).
@ -225,7 +225,7 @@ config :pleroma, :mrf_user_allowlist, %{
This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. You can find the documentation for `pleroma_fe` configuration into [Pleroma-FE configuration and customization for instance administrators](/frontend/CONFIGURATION/#options). This can be used to configure a keyword list that keeps the configuration data for any kind of frontend. By default, settings for `pleroma_fe` and `masto_fe` are configured. You can find the documentation for `pleroma_fe` configuration into [Pleroma-FE configuration and customization for instance administrators](/frontend/CONFIGURATION/#options).
Frontends can access these settings at `/api/pleroma/frontend_configurations` Frontends can access these settings at `/api/v1/pleroma/frontend_configurations`
To add your own configuration for PleromaFE, use it like this: To add your own configuration for PleromaFE, use it like this:
@ -848,13 +848,13 @@ config :pleroma, :admin_token, "somerandomtoken"
You can then do You can then do
```shell ```shell
curl "http://localhost:4000/api/pleroma/admin/users/invites?admin_token=somerandomtoken" curl "http://localhost:4000/api/v1/pleroma/admin/users/invites?admin_token=somerandomtoken"
``` ```
or or
```shell ```shell
curl -H "X-Admin-Token: somerandomtoken" "http://localhost:4000/api/pleroma/admin/users/invites" curl -H "X-Admin-Token: somerandomtoken" "http://localhost:4000/api/v1/pleroma/admin/users/invites"
``` ```
Warning: it's discouraged to use this feature because of the associated security risk: static / rarely changed instance-wide token is much weaker compared to email-password pair of a real admin user; consider using HTTP Basic Auth or OAuth-based authentication instead. Warning: it's discouraged to use this feature because of the associated security risk: static / rarely changed instance-wide token is much weaker compared to email-password pair of a real admin user; consider using HTTP Basic Auth or OAuth-based authentication instead.

154
docs/development/API/admin_api.md
View file

@ -2,7 +2,9 @@
Authentication is required and the user must be an admin. Authentication is required and the user must be an admin.
## `GET /api/pleroma/admin/users` The `/api/v1/pleroma/admin/*` path is backwards compatible with `/api/pleroma/admin/*` (`/api/pleroma/admin/*` will be deprecated in the future).
## `GET /api/v1/pleroma/admin/users`
### List users ### List users
@ -23,7 +25,7 @@ Authentication is required and the user must be an admin.
- *optional* `actor_types`: **[string]** actor type list (`Person`, `Service`, `Application`) - *optional* `actor_types`: **[string]** actor type list (`Person`, `Service`, `Application`)
- *optional* `name`: **string** user display name - *optional* `name`: **string** user display name
- *optional* `email`: **string** user email - *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` - Example: `https://mypleroma.org/api/v1/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: - Response:
```json ```json
@ -52,7 +54,7 @@ Authentication is required and the user must be an admin.
} }
``` ```
## DEPRECATED `DELETE /api/pleroma/admin/users` ## DEPRECATED `DELETE /api/v1/pleroma/admin/users`
### Remove a user ### Remove a user
@ -60,7 +62,7 @@ Authentication is required and the user must be an admin.
- `nickname` - `nickname`
- Response: User’s nickname - Response: User’s nickname
## `DELETE /api/pleroma/admin/users` ## `DELETE /api/v1/pleroma/admin/users`
### Remove a user ### Remove a user
@ -81,7 +83,7 @@ Authentication is required and the user must be an admin.
] ]
- Response: User’s nickname - Response: User’s nickname
## `POST /api/pleroma/admin/users/follow` ## `POST /api/v1/pleroma/admin/users/follow`
### Make a user follow another user ### Make a user follow another user
@ -91,7 +93,7 @@ Authentication is required and the user must be an admin.
- Response: - Response:
- "ok" - "ok"
## `POST /api/pleroma/admin/users/unfollow` ## `POST /api/v1/pleroma/admin/users/unfollow`
### Make a user unfollow another user ### Make a user unfollow another user
@ -101,7 +103,7 @@ Authentication is required and the user must be an admin.
- Response: - Response:
- "ok" - "ok"
## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation` ## `PATCH /api/v1/pleroma/admin/users/:nickname/toggle_activation`
### Toggle user activation ### Toggle user activation
@ -117,7 +119,7 @@ Authentication is required and the user must be an admin.
} }
``` ```
## `PUT /api/pleroma/admin/users/tag` ## `PUT /api/v1/pleroma/admin/users/tag`
### Tag a list of users ### Tag a list of users
@ -125,7 +127,7 @@ Authentication is required and the user must be an admin.
- `nicknames` (array) - `nicknames` (array)
- `tags` (array) - `tags` (array)
## `DELETE /api/pleroma/admin/users/tag` ## `DELETE /api/v1/pleroma/admin/users/tag`
### Untag a list of users ### Untag a list of users
@ -133,7 +135,7 @@ Authentication is required and the user must be an admin.
- `nicknames` (array) - `nicknames` (array)
- `tags` (array) - `tags` (array)
## `GET /api/pleroma/admin/users/:nickname/permission_group` ## `GET /api/v1/pleroma/admin/users/:nickname/permission_group`
### Get user user permission groups membership ### Get user user permission groups membership
@ -147,7 +149,7 @@ Authentication is required and the user must be an admin.
} }
``` ```
## `GET /api/pleroma/admin/users/:nickname/permission_group/:permission_group` ## `GET /api/v1/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.
@ -163,7 +165,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## DEPRECATED `POST /api/pleroma/admin/users/:nickname/permission_group/:permission_group` ## DEPRECATED `POST /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`
### Add user to permission group ### Add user to permission group
@ -172,7 +174,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- On failure: `{"error": "…"}` - On failure: `{"error": "…"}`
- On success: JSON of the user - On success: JSON of the user
## `POST /api/pleroma/admin/users/permission_group/:permission_group` ## `POST /api/v1/pleroma/admin/users/permission_group/:permission_group`
### Add users to permission group ### Add users to permission group
@ -182,9 +184,9 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- On failure: `{"error": "…"}` - On failure: `{"error": "…"}`
- On success: JSON of the user - On success: JSON of the user
## DEPRECATED `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group` ## DEPRECATED `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`
## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group` ## `DELETE /api/v1/pleroma/admin/users/:nickname/permission_group/:permission_group`
### Remove user from permission group ### Remove user from permission group
@ -194,7 +196,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- On success: JSON of the user - On success: JSON of the user
- Note: An admin cannot revoke their own admin status. - Note: An admin cannot revoke their own admin status.
## `DELETE /api/pleroma/admin/users/permission_group/:permission_group` ## `DELETE /api/v1/pleroma/admin/users/permission_group/:permission_group`
### Remove users from permission group ### Remove users from permission group
@ -205,7 +207,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- On success: JSON of the user - On success: JSON of the user
- Note: An admin cannot revoke their own admin status. - Note: An admin cannot revoke their own admin status.
## `PATCH /api/pleroma/admin/users/activate` ## `PATCH /api/v1/pleroma/admin/users/activate`
### Activate user ### Activate user
@ -223,7 +225,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `PATCH /api/pleroma/admin/users/deactivate` ## `PATCH /api/v1/pleroma/admin/users/deactivate`
### Deactivate user ### Deactivate user
@ -241,7 +243,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `PATCH /api/pleroma/admin/users/approve` ## `PATCH /api/v1/pleroma/admin/users/approve`
### Approve user ### Approve user
@ -259,7 +261,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `GET /api/pleroma/admin/users/:nickname_or_id` ## `GET /api/v1/pleroma/admin/users/:nickname_or_id`
### Retrive the details of a user ### Retrive the details of a user
@ -269,7 +271,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- On failure: `Not found` - On failure: `Not found`
- On success: JSON of the user - On success: JSON of the user
## `GET /api/pleroma/admin/users/:nickname_or_id/statuses` ## `GET /api/v1/pleroma/admin/users/:nickname_or_id/statuses`
### Retrive user's latest statuses ### Retrive user's latest statuses
@ -293,7 +295,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `GET /api/pleroma/admin/instances/:instance/statuses` ## `GET /api/v1/pleroma/admin/instances/:instance/statuses`
### Retrive instance's latest statuses ### Retrive instance's latest statuses
@ -317,7 +319,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
} }
``` ```
## `GET /api/pleroma/admin/statuses` ## `GET /api/v1/pleroma/admin/statuses`
### Retrives all latest statuses ### Retrives all latest statuses
@ -330,7 +332,7 @@ 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
## `GET /api/pleroma/admin/relay` ## `GET /api/v1/pleroma/admin/relay`
### List Relays ### List Relays
@ -346,7 +348,7 @@ Response:
] ]
``` ```
## `POST /api/pleroma/admin/relay` ## `POST /api/v1/pleroma/admin/relay`
### Follow a Relay ### Follow a Relay
@ -362,7 +364,7 @@ Response:
{"actor": "https://example.com/relay", "followed_back": true} {"actor": "https://example.com/relay", "followed_back": true}
``` ```
## `DELETE /api/pleroma/admin/relay` ## `DELETE /api/v1/pleroma/admin/relay`
### Unfollow a Relay ### Unfollow a Relay
@ -378,7 +380,7 @@ Response:
{"https://example.com/relay"} {"https://example.com/relay"}
``` ```
## `POST /api/pleroma/admin/users/invite_token` ## `POST /api/v1/pleroma/admin/users/invite_token`
### Create an account registration invite token ### Create an account registration invite token
@ -399,7 +401,7 @@ Response:
} }
``` ```
## `GET /api/pleroma/admin/users/invites` ## `GET /api/v1/pleroma/admin/users/invites`
### Get a list of generated invites ### Get a list of generated invites
@ -424,7 +426,7 @@ Response:
} }
``` ```
## `POST /api/pleroma/admin/users/revoke_invite` ## `POST /api/v1/pleroma/admin/users/revoke_invite`
### Revoke invite by token ### Revoke invite by token
@ -445,7 +447,7 @@ Response:
} }
``` ```
## `POST /api/pleroma/admin/users/email_invite` ## `POST /api/v1/pleroma/admin/users/email_invite`
### Sends registration invite via email ### Sends registration invite via email
@ -466,7 +468,7 @@ Response:
] ]
``` ```
## `GET /api/pleroma/admin/users/:nickname/password_reset` ## `GET /api/v1/pleroma/admin/users/:nickname/password_reset`
### Get a password reset token for a given nickname ### Get a password reset token for a given nickname
@ -477,11 +479,11 @@ Response:
```json ```json
{ {
"token": "base64 reset token", "token": "base64 reset token",
"link": "https://pleroma.social/api/pleroma/password_reset/url-encoded-base64-token" "link": "https://pleroma.social/api/v1/pleroma/password_reset/url-encoded-base64-token"
} }
``` ```
## `PATCH /api/pleroma/admin/users/force_password_reset` ## `PATCH /api/v1/pleroma/admin/users/force_password_reset`
### Force passord reset for a user with a given nickname ### Force passord reset for a user with a given nickname
@ -489,7 +491,7 @@ Response:
- `nicknames` - `nicknames`
- Response: none (code `204`) - Response: none (code `204`)
## PUT `/api/pleroma/admin/users/disable_mfa` ## PUT `/api/v1/pleroma/admin/users/disable_mfa`
### Disable mfa for user's account. ### Disable mfa for user's account.
@ -497,7 +499,7 @@ Response:
- `nickname` - `nickname`
- Response: User’s nickname - Response: User’s nickname
## `GET /api/pleroma/admin/users/:nickname/credentials` ## `GET /api/v1/pleroma/admin/users/:nickname/credentials`
### Get the user's email, password, display and settings-related fields ### Get the user's email, password, display and settings-related fields
@ -545,7 +547,7 @@ Response:
} }
``` ```
## `PATCH /api/pleroma/admin/users/:nickname/credentials` ## `PATCH /api/v1/pleroma/admin/users/:nickname/credentials`
### Change the user's email, password, display and settings-related fields ### Change the user's email, password, display and settings-related fields
@ -596,7 +598,7 @@ Status: 404
{"error": "Not found"} {"error": "Not found"}
``` ```
## `GET /api/pleroma/admin/reports` ## `GET /api/v1/pleroma/admin/reports`
### Get a list of reports ### Get a list of reports
@ -756,17 +758,17 @@ Status: 404
} }
``` ```
## `GET /api/pleroma/admin/grouped_reports` ## `GET /api/v1/pleroma/admin/grouped_reports`
### Get a list of reports, grouped by status ### Get a list of reports, grouped by status
- Params: none - Params: none
- On success: JSON, returns a list of reports, where: - On success: JSON, returns a list of reports, where:
- `date`: date of the latest report - `date`: date of the latest report
- `account`: the user who has been reported (see `/api/pleroma/admin/reports` for reference) - `account`: the user who has been reported (see `/api/v1/pleroma/admin/reports` for reference)
- `status`: reported status (see `/api/pleroma/admin/reports` for reference) - `status`: reported status (see `/api/v1/pleroma/admin/reports` for reference)
- `actors`: users who had reported this status (see `/api/pleroma/admin/reports` for reference) - `actors`: users who had reported this status (see `/api/v1/pleroma/admin/reports` for reference)
- `reports`: reports (see `/api/pleroma/admin/reports` for reference) - `reports`: reports (see `/api/v1/pleroma/admin/reports` for reference)
```json ```json
"reports": [ "reports": [
@ -780,7 +782,7 @@ Status: 404
] ]
``` ```
## `GET /api/pleroma/admin/reports/:id` ## `GET /api/v1/pleroma/admin/reports/:id`
### Get an individual report ### Get an individual report
@ -792,7 +794,7 @@ Status: 404
- 404 Not Found `"Not found"` - 404 Not Found `"Not found"`
- On success: JSON, Report object (see above) - On success: JSON, Report object (see above)
## `PATCH /api/pleroma/admin/reports` ## `PATCH /api/v1/pleroma/admin/reports`
### Change the state of one or multiple reports ### Change the state of one or multiple reports
@ -823,7 +825,7 @@ Status: 404
- On success: `204`, empty response - On success: `204`, empty response
## `POST /api/pleroma/admin/reports/:id/notes` ## `POST /api/v1/pleroma/admin/reports/:id/notes`
### Create report note ### Create report note
@ -835,7 +837,7 @@ Status: 404
- 400 Bad Request `"Invalid parameters"` when `status` is missing - 400 Bad Request `"Invalid parameters"` when `status` is missing
- On success: `204`, empty response - On success: `204`, empty response
## `DELETE /api/pleroma/admin/reports/:report_id/notes/:id` ## `DELETE /api/v1/pleroma/admin/reports/:report_id/notes/:id`
### Delete report note ### Delete report note
@ -847,7 +849,7 @@ Status: 404
- 400 Bad Request `"Invalid parameters"` when `status` is missing - 400 Bad Request `"Invalid parameters"` when `status` is missing
- On success: `204`, empty response - On success: `204`, empty response
## `GET /api/pleroma/admin/statuses/:id` ## `GET /api/v1/pleroma/admin/statuses/:id`
### Show status by id ### Show status by id
@ -858,7 +860,7 @@ Status: 404
- 404 Not Found `"Not Found"` - 404 Not Found `"Not Found"`
- On success: JSON, Mastodon Status entity - On success: JSON, Mastodon Status entity
## `PUT /api/pleroma/admin/statuses/:id` ## `PUT /api/v1/pleroma/admin/statuses/:id`
### Change the scope of an individual reported status ### Change the scope of an individual reported status
@ -873,7 +875,7 @@ Status: 404
- 404 Not Found `"Not found"` - 404 Not Found `"Not found"`
- On success: JSON, Mastodon Status entity - On success: JSON, Mastodon Status entity
## `DELETE /api/pleroma/admin/statuses/:id` ## `DELETE /api/v1/pleroma/admin/statuses/:id`
### Delete an individual reported status ### Delete an individual reported status
@ -885,7 +887,7 @@ Status: 404
- 404 Not Found `"Not found"` - 404 Not Found `"Not found"`
- On success: 200 OK `{}` - On success: 200 OK `{}`
## `GET /api/pleroma/admin/restart` ## `GET /api/v1/pleroma/admin/restart`
### Restarts pleroma application ### Restarts pleroma application
@ -900,7 +902,7 @@ Status: 404
{} {}
``` ```
## `GET /api/pleroma/admin/need_reboot` ## `GET /api/v1/pleroma/admin/need_reboot`
### Returns the flag whether the pleroma should be restarted ### Returns the flag whether the pleroma should be restarted
@ -913,7 +915,7 @@ Status: 404
} }
``` ```
## `GET /api/pleroma/admin/config` ## `GET /api/v1/pleroma/admin/config`
### Get list of merged default settings with saved in database. ### Get list of merged default settings with saved in database.
@ -940,7 +942,7 @@ Status: 404
} }
``` ```
## `POST /api/pleroma/admin/config` ## `POST /api/v1/pleroma/admin/config`
### Update config settings ### Update config settings
@ -1089,7 +1091,7 @@ config :quack,
} }
``` ```
## ` GET /api/pleroma/admin/config/descriptions` ## ` GET /api/v1/pleroma/admin/config/descriptions`
### Get JSON with config descriptions. ### Get JSON with config descriptions.
Loads json generated from `config/descriptions.exs`. Loads json generated from `config/descriptions.exs`.
@ -1122,7 +1124,7 @@ Loads json generated from `config/descriptions.exs`.
}] }]
``` ```
## `GET /api/pleroma/admin/moderation_log` ## `GET /api/v1/pleroma/admin/moderation_log`
### Get moderation log ### Get moderation log
@ -1152,7 +1154,7 @@ Loads json generated from `config/descriptions.exs`.
] ]
``` ```
## `POST /api/pleroma/admin/reload_emoji` ## `POST /api/v1/pleroma/admin/reload_emoji`
### Reload the instance's custom emoji ### Reload the instance's custom emoji
@ -1160,7 +1162,7 @@ Loads json generated from `config/descriptions.exs`.
- Params: None - Params: None
- Response: JSON, "ok" and 200 status - Response: JSON, "ok" and 200 status
## `PATCH /api/pleroma/admin/users/confirm_email` ## `PATCH /api/v1/pleroma/admin/users/confirm_email`
### Confirm users' emails ### Confirm users' emails
@ -1168,7 +1170,7 @@ Loads json generated from `config/descriptions.exs`.
- `nicknames` - `nicknames`
- Response: Array of user nicknames - Response: Array of user nicknames
## `PATCH /api/pleroma/admin/users/resend_confirmation_email` ## `PATCH /api/v1/pleroma/admin/users/resend_confirmation_email`
### Resend confirmation email ### Resend confirmation email
@ -1176,13 +1178,13 @@ Loads json generated from `config/descriptions.exs`.
- `nicknames` - `nicknames`
- Response: Array of user nicknames - Response: Array of user nicknames
## `GET /api/pleroma/admin/stats` ## `GET /api/v1/pleroma/admin/stats`
### Stats ### Stats
- Query Params: - Query Params:
- *optional* `instance`: **string** instance hostname (without protocol) to get stats for - *optional* `instance`: **string** instance hostname (without protocol) to get stats for
- Example: `https://mypleroma.org/api/pleroma/admin/stats?instance=lain.com` - Example: `https://mypleroma.org/api/v1/pleroma/admin/stats?instance=lain.com`
- Response: - Response:
@ -1197,7 +1199,7 @@ Loads json generated from `config/descriptions.exs`.
} }
``` ```
## `GET /api/pleroma/admin/oauth_app` ## `GET /api/v1/pleroma/admin/oauth_app`
### List OAuth app ### List OAuth app
@ -1229,7 +1231,7 @@ Loads json generated from `config/descriptions.exs`.
``` ```
## `POST /api/pleroma/admin/oauth_app` ## `POST /api/v1/pleroma/admin/oauth_app`
### Create OAuth App ### Create OAuth App
@ -1262,7 +1264,7 @@ Loads json generated from `config/descriptions.exs`.
} }
``` ```
## `PATCH /api/pleroma/admin/oauth_app/:id` ## `PATCH /api/v1/pleroma/admin/oauth_app/:id`
### Update OAuth App ### Update OAuth App
@ -1287,7 +1289,7 @@ Loads json generated from `config/descriptions.exs`.
} }
``` ```
## `DELETE /api/pleroma/admin/oauth_app/:id` ## `DELETE /api/v1/pleroma/admin/oauth_app/:id`
### Delete OAuth App ### Delete OAuth App
@ -1298,7 +1300,7 @@ Loads json generated from `config/descriptions.exs`.
- On failure: - On failure:
- 400 Bad Request `"Invalid parameters"` when `status` is missing - 400 Bad Request `"Invalid parameters"` when `status` is missing
## `GET /api/pleroma/admin/media_proxy_caches` ## `GET /api/v1/pleroma/admin/media_proxy_caches`
### Get a list of all banned MediaProxy URLs in Cachex ### Get a list of all banned MediaProxy URLs in Cachex
@ -1322,7 +1324,7 @@ Loads json generated from `config/descriptions.exs`.
``` ```
## `POST /api/pleroma/admin/media_proxy_caches/delete` ## `POST /api/v1/pleroma/admin/media_proxy_caches/delete`
### Remove a banned MediaProxy URL from Cachex ### Remove a banned MediaProxy URL from Cachex
@ -1337,7 +1339,7 @@ Loads json generated from `config/descriptions.exs`.
``` ```
## `POST /api/pleroma/admin/media_proxy_caches/purge` ## `POST /api/v1/pleroma/admin/media_proxy_caches/purge`
### Purge a MediaProxy URL ### Purge a MediaProxy URL
@ -1353,7 +1355,7 @@ Loads json generated from `config/descriptions.exs`.
``` ```
## GET /api/pleroma/admin/users/:nickname/chats ## GET /api/v1/pleroma/admin/users/:nickname/chats
### List a user's chats ### List a user's chats
@ -1382,7 +1384,7 @@ Loads json generated from `config/descriptions.exs`.
] ]
``` ```
## GET /api/pleroma/admin/chats/:chat_id ## GET /api/v1/pleroma/admin/chats/:chat_id
### View a single chat ### View a single chat
@ -1409,7 +1411,7 @@ Loads json generated from `config/descriptions.exs`.
} }
``` ```
## GET /api/pleroma/admin/chats/:chat_id/messages ## GET /api/v1/pleroma/admin/chats/:chat_id/messages
### List the messages in a chat ### List the messages in a chat
@ -1447,7 +1449,7 @@ Loads json generated from `config/descriptions.exs`.
] ]
``` ```
## DELETE /api/pleroma/admin/chats/:chat_id/messages/:message_id ## DELETE /api/v1/pleroma/admin/chats/:chat_id/messages/:message_id
### Delete a single message ### Delete a single message
@ -1474,7 +1476,7 @@ Loads json generated from `config/descriptions.exs`.
} }
``` ```
## `GET /api/pleroma/admin/instance_document/:document_name` ## `GET /api/v1/pleroma/admin/instance_document/:document_name`
### Get an instance document ### Get an instance document
@ -1488,7 +1490,7 @@ Returns the content of the document
<h1>Instance panel</h1> <h1>Instance panel</h1>
``` ```
## `PATCH /api/pleroma/admin/instance_document/:document_name` ## `PATCH /api/v1/pleroma/admin/instance_document/:document_name`
- Params: - Params:
- `file` (the file to be uploaded, using multipart form data.) - `file` (the file to be uploaded, using multipart form data.)
@ -1504,7 +1506,7 @@ Returns the content of the document
} }
``` ```
## `DELETE /api/pleroma/admin/instance_document/:document_name` ## `DELETE /api/v1/pleroma/admin/instance_document/:document_name`
### Delete an instance document ### Delete an instance document
@ -1516,7 +1518,7 @@ Returns the content of the document
} }
``` ```
## `GET /api/pleroma/admin/frontends ## `GET /api/v1/pleroma/admin/frontends
### List available frontends ### List available frontends
@ -1541,7 +1543,7 @@ Returns the content of the document
] ]
``` ```
## `POST /api/pleroma/admin/frontends/install` ## `POST /api/v1/pleroma/admin/frontends/install`
### Install a frontend ### Install a frontend

2
docs/development/API/differences_in_mastoapi_responses.md
View file

@ -97,7 +97,7 @@ Has these additional fields under the `pleroma` object:
- `allow_following_move`: boolean, true when the user allows automatically follow moved following accounts - `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_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. - `unread_notifications_count`: The count of unread notifications. Only returned to the account owner.
- `notification_settings`: object, can be absent. See `/api/pleroma/notification_settings` for the parameters/keys returned. - `notification_settings`: object, can be absent. See `/api/v1/pleroma/notification_settings` for the parameters/keys returned.
- `accepts_chat_messages`: boolean, but can be null if we don't have that information about a user - `accepts_chat_messages`: boolean, but can be null if we don't have that information about a user
- `favicon`: nullable URL string, Favicon image of the user's instance - `favicon`: nullable URL string, Favicon image of the user's instance

58
docs/development/API/pleroma_api.md
View file

@ -4,7 +4,9 @@ Requests that require it can be authenticated with [an OAuth token](https://tool
Request parameters can be passed via [query strings](https://en.wikipedia.org/wiki/Query_string) or as [form data](https://www.w3.org/TR/html401/interact/forms.html). Files must be uploaded as `multipart/form-data`. Request parameters can be passed via [query strings](https://en.wikipedia.org/wiki/Query_string) or as [form data](https://www.w3.org/TR/html401/interact/forms.html). Files must be uploaded as `multipart/form-data`.
## `/api/pleroma/emoji` The `/api/v1/pleroma/*` path is backwards compatible with `/api/pleroma/*` (`/api/pleroma/*` will be deprecated in the future).
## `/api/v1/pleroma/emoji`
### Lists the custom emoji on that server. ### Lists the custom emoji on that server.
* Method: `GET` * Method: `GET`
* Authentication: not required * Authentication: not required
@ -35,7 +37,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
``` ```
* Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format * Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format
## `/api/pleroma/follow_import` ## `/api/v1/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
@ -44,7 +46,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* 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/pleroma/blocks_import` ## `/api/v1/pleroma/blocks_import`
### Imports your blocks. ### Imports your blocks.
* Method: `POST` * Method: `POST`
* Authentication: required * Authentication: required
@ -52,7 +54,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* `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/pleroma/mutes_import` ## `/api/v1/pleroma/mutes_import`
### Imports your mutes. ### Imports your mutes.
* Method: `POST` * Method: `POST`
* Authentication: required * Authentication: required
@ -60,7 +62,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* `list`: STRING or FILE containing a whitespace-separated list of accounts to mute * `list`: STRING or FILE containing a whitespace-separated list of accounts to mute
* Response: HTTP 200 on success, 500 on error * Response: HTTP 200 on success, 500 on error
## `/api/pleroma/captcha` ## `/api/v1/pleroma/captcha`
### Get a new captcha ### Get a new captcha
* Method: `GET` * Method: `GET`
* Authentication: not required * Authentication: not required
@ -68,7 +70,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* 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/pleroma/delete_account` ## `/api/v1/pleroma/delete_account`
### Delete an account ### Delete an account
* Method `POST` * Method `POST`
* Authentication: required * Authentication: required
@ -77,7 +79,7 @@ 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 * 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/pleroma/disable_account` ## `/api/v1/pleroma/disable_account`
### Disable an account ### Disable an account
* Method `POST` * Method `POST`
* Authentication: required * Authentication: required
@ -86,21 +88,21 @@ 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 * 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/pleroma/accounts/mfa` ## `/api/v1/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 `{"enabled": "false", "totp": false }`
## `/api/pleroma/accounts/mfa/setup/totp` ## `/api/v1/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/pleroma/accounts/mfa/confirm/totp` ## `/api/v1/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
@ -111,7 +113,7 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* 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/pleroma/accounts/mfa/totp` ## `/api/v1/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
@ -121,14 +123,14 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* 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/pleroma/accounts/mfa/backup_codes` ## `/api/v1/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
* OAuth scope: `write:security` * OAuth scope: `write:security`
* Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}` * Response: JSON. Returns `{"codes": codes}`when successful, otherwise HTTP 422 `{"error": "[error message]"}`
## `/api/pleroma/admin/` ## `/api/v1/pleroma/admin/`
See [Admin-API](admin_api.md) See [Admin-API](admin_api.md)
## `/api/v1/pleroma/notifications/read` ## `/api/v1/pleroma/notifications/read`
@ -298,7 +300,7 @@ See [Admin-API](admin_api.md)
* Note: Behaves exactly the same as `POST /api/v1/upload`. * 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`. Can only accept images - any attempt to upload non-image files will be met with `HTTP 415 Unsupported Media Type`.
## `/api/pleroma/notification_settings` ## `/api/v1/pleroma/notification_settings`
### Updates user notification settings ### Updates user notification settings
* Method `PUT` * Method `PUT`
* Authentication: required * Authentication: required
@ -307,7 +309,7 @@ See [Admin-API](admin_api.md)
* `hide_notification_contents`: BOOLEAN field. When set to true, it removes the contents of a message from the push notification. * `hide_notification_contents`: 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"}` * Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}`
## `/api/pleroma/healthcheck` ## `/api/v1/pleroma/healthcheck`
### Healthcheck endpoint with additional system data. ### Healthcheck endpoint with additional system data.
* Method `GET` * Method `GET`
* Authentication: not required * Authentication: not required
@ -325,7 +327,7 @@ See [Admin-API](admin_api.md)
} }
``` ```
## `/api/pleroma/change_email` ## `/api/v1/pleroma/change_email`
### Change account email ### Change account email
* Method `POST` * Method `POST`
* Authentication: required * Authentication: required
@ -378,7 +380,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* Params: None * Params: None
* Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy). * Response: JSON, returns a list of Mastodon Conversation entities that were marked as read (200 - healthy, 503 unhealthy).
## `GET /api/pleroma/emoji/pack?name=:name` ## `GET /api/v1/pleroma/emoji/pack?name=:name`
### Get pack.json for the pack ### Get pack.json for the pack
@ -397,7 +399,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
} }
``` ```
## `POST /api/pleroma/emoji/pack?name=:name` ## `POST /api/v1/pleroma/emoji/pack?name=:name`
### Creates an empty pack ### Creates an empty pack
@ -407,7 +409,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* `name`: pack name * `name`: pack name
* Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists * Response: JSON, "ok" and 200 status or 409 if the pack with that name already exists
## `PATCH /api/pleroma/emoji/pack?name=:name` ## `PATCH /api/v1/pleroma/emoji/pack?name=:name`
### Updates (replaces) pack metadata ### Updates (replaces) pack metadata
@ -425,7 +427,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* Response: JSON, updated "metadata" section of the pack and 200 status or 400 if there was a * 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) problem with the new metadata (the error is specified in the "error" part of the response JSON)
## `DELETE /api/pleroma/emoji/pack?name=:name` ## `DELETE /api/v1/pleroma/emoji/pack?name=:name`
### Delete a custom emoji pack ### Delete a custom emoji pack
@ -435,7 +437,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* `name`: pack name * `name`: pack name
* Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack * Response: JSON, "ok" and 200 status or 500 if there was an error deleting the pack
## `GET /api/pleroma/emoji/packs/import` ## `GET /api/v1/pleroma/emoji/packs/import`
### Imports packs from filesystem ### Imports packs from filesystem
@ -444,7 +446,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* Params: None * Params: None
* Response: JSON, returns a list of imported packs. * Response: JSON, returns a list of imported packs.
## `GET /api/pleroma/emoji/packs/remote` ## `GET /api/v1/pleroma/emoji/packs/remote`
### Make request to another instance for packs list ### Make request to another instance for packs list
@ -456,7 +458,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* `page_size`: page size for packs (default 50) * `page_size`: page size for packs (default 50)
* Response: JSON with the pack list, hashmap with pack name and pack contents * Response: JSON with the pack list, hashmap with pack name and pack contents
## `POST /api/pleroma/emoji/packs/download` ## `POST /api/v1/pleroma/emoji/packs/download`
### Download pack from another instance ### Download pack from another instance
@ -469,7 +471,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were * Response: JSON, "ok" with 200 status if the pack was downloaded, or 500 if there were
errors downloading the pack errors downloading the pack
## `POST /api/pleroma/emoji/packs/files?name=:name` ## `POST /api/v1/pleroma/emoji/packs/files?name=:name`
### Add new file to the pack ### Add new file to the pack
@ -482,7 +484,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* `filename`: (*optional*) new emoji file name. If not specified 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. * 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/files?name=:name` ## `PATCH /api/v1/pleroma/emoji/packs/files?name=:name`
### Update emoji file from pack ### Update emoji file from pack
@ -496,7 +498,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* `force`: (*optional*) with true value to overwrite existing emoji with new shortcode * `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. * 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/files?name=:name` ## `DELETE /api/v1/pleroma/emoji/packs/files?name=:name`
### Delete emoji file from pack ### Delete emoji file from pack
@ -507,7 +509,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* `shortcode`: emoji file shortcode * `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. * 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` ## `GET /api/v1/pleroma/emoji/packs`
### Lists local custom emoji packs ### Lists local custom emoji packs
@ -528,7 +530,7 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
} }
``` ```
## `GET /api/pleroma/emoji/packs/archive?name=:name` ## `GET /api/v1/pleroma/emoji/packs/archive?name=:name`
### Requests a local pack archive from the instance ### Requests a local pack archive from the instance