diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/admin_api.md | 171 | ||||
| -rw-r--r-- | docs/api/differences_in_mastoapi_responses.md | 34 | ||||
| -rw-r--r-- | docs/api/pleroma_api.md | 64 |
3 files changed, 236 insertions, 33 deletions
diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index b45c5e285..7ccb90836 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -38,7 +38,9 @@ Authentication is required and the user must be an admin. "moderator": bool }, "local": bool, - "tags": array + "tags": array, + "avatar": string, + "display_name": string }, ... ] @@ -174,17 +176,30 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `nickname` - `status` BOOLEAN field, false value means deactivation. -## `/api/pleroma/admin/users/:nickname` +## `/api/pleroma/admin/users/:nickname_or_id` ### Retrive the details of a user - Method: `GET` - Params: - - `nickname` + - `nickname` or `id` - Response: - On failure: `Not found` - On success: JSON of the user +## `/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 +- Response: + - On failure: `Not found` + - On success: JSON array of user's latest statuses + ## `/api/pleroma/admin/relay` ### Follow a Relay @@ -289,7 +304,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `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: +- 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 @@ -331,6 +346,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret "pleroma": {}, "sensitive": false }, + "tags": ["force_unlisted"], "statuses_count": 3, "url": "https://pleroma.example.org/users/user", "username": "user" @@ -366,6 +382,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret "pleroma": {}, "sensitive": false }, + "tags": ["force_unlisted"], "statuses_count": 1, "url": "https://pleroma.example.org/users/lain", "username": "lain" @@ -443,7 +460,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Params: - `id` - Response: - - On failure: + - On failure: - 403 Forbidden `{"error": "error_msg"}` - 404 Not Found `"Not found"` - On success: JSON, Report object (see above) @@ -454,8 +471,8 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Params: - `id` - `state`: required, the new state. Valid values are `open`, `closed` and `resolved` -- Response: - - On failure: +- Response: + - On failure: - 400 Bad Request `"Unsupported state"` - 403 Forbidden `{"error": "error_msg"}` - 404 Not Found `"Not found"` @@ -467,10 +484,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Params: - `id` - `status`: required, the message -- Response: - - On failure: - - 400 Bad Request `"Invalid parameters"` when `status` is missing - - 403 Forbidden `{"error": "error_msg"}` +- 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 @@ -540,10 +557,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `id` - `sensitive`: optional, valid values are `true` or `false` - `visibility`: optional, valid values are `public`, `private` and `unlisted` -- Response: - - On failure: +- Response: + - On failure: - 400 Bad Request `"Unsupported visibility"` - - 403 Forbidden `{"error": "error_msg"}` + - 403 Forbidden `{"error": "error_msg"}` - 404 Not Found `"Not found"` - On success: JSON, Mastodon Status entity @@ -552,8 +569,128 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Method `DELETE` - Params: - `id` -- Response: - - On failure: - - 403 Forbidden `{"error": "error_msg"}` +- Response: + - On failure: + - 403 Forbidden `{"error": "error_msg"}` - 404 Not Found `"Not found"` - On success: 200 OK `{}` + + +## `/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: + +```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` +- Params: none +- Response: + +```json +{} +``` + +## `/api/pleroma/admin/config` +### List config settings +List config settings only works with `:pleroma => :instance => :dynamic_configuration` setting to `true`. +- Method `GET` +- Params: none +- Response: + +```json +{ + configs: [ + { + "group": string, + "key": string or string with leading `:` for atoms, + "value": string or {} or [] or {"tuple": []} + } + ] +} +``` + +## `/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: + - `:hackney_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) + ] + +- Request (example): + +```json +{ + configs: [ + { + "group": "pleroma", + "key": "Pleroma.Upload", + "value": [ + {"tuple": [":uploader", "Pleroma.Uploaders.Local"]}, + {"tuple": [":filters", ["Pleroma.Upload.Filter.Dedupe"]]}, + {"tuple": [":link_name", true]}, + {"tuple": [":proxy_remote", false]}, + {"tuple": [":proxy_opts", [ + {"tuple": [":redirect_on_failure", false]}, + {"tuple": [":max_body_length", 1048576]}, + {"tuple": [":http": [ + {"tuple": [":follow_redirect", true]}, + {"tuple": [":pool", ":upload"]}, + ]]} + ] + ]}, + {"tuple": [":dispatch", { + "tuple": ["/api/v1/streaming", "Pleroma.Web.MastodonAPI.WebsocketHandler", []] + }]} + ] + } + ] +} + +- Response: + +```json +{ + configs: [ + { + "group": string, + "key": string or string with leading `:` for atoms, + "value": string or {} or [] or {"tuple": []} + } + ] +} +``` diff --git a/docs/api/differences_in_mastoapi_responses.md b/docs/api/differences_in_mastoapi_responses.md index 36b47608e..f34e3dd72 100644 --- a/docs/api/differences_in_mastoapi_responses.md +++ b/docs/api/differences_in_mastoapi_responses.md @@ -16,13 +16,16 @@ Adding the parameter `with_muted=true` to the timeline queries will also return ## Statuses +- `visibility`: has an additional possible value `list` + Has these additional fields under the `pleroma` object: -- `local`: true if the post was made on the local instance. +- `local`: true if the post was made on the local instance - `conversation_id`: the ID of the conversation the status is associated with (if any) - `in_reply_to_account_acct`: the `acct` property of User entity for replied user (if any) - `content`: a map consisting of alternate representations of the `content` property with the key being it's mimetype. Currently the only alternate representation supported is `text/plain` - `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 ## Attachments @@ -32,7 +35,10 @@ Has these additional fields under the `pleroma` object: ## Accounts -- `/api/v1/accounts/:id`: The `id` parameter can also be the `nickname` of the user. This only works in this endpoint, not the deeper nested ones for following etc. +The `id` parameter can also be the `nickname` of the user. This only works in these endpoints, not the deeper nested ones for following etc. + +- `/api/v1/accounts/:id` +- `/api/v1/accounts/:id/statuses` Has these additional fields under the `pleroma` object: @@ -43,6 +49,9 @@ Has these additional fields under the `pleroma` object: - `confirmation_pending`: boolean, true if a new user account is waiting on email confirmation to be activated - `hide_followers`: boolean, true when the user has follower hiding enabled - `hide_follows`: boolean, true when the user has follow hiding enabled +- `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 ### Source @@ -51,12 +60,19 @@ 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 +## Conversations + +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. + ## Account Search Behavior has changed: - `/api/v1/accounts/search`: Does not require authentication + ## Notifications Has these additional fields under the `pleroma` object: @@ -69,6 +85,10 @@ Additional parameters can be added to the JSON body/Form data: - `preview`: boolean, if set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example. - `content_type`: string, contain the MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint. +- `to`: A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply. +- `visibility`: string, besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`. +- `expires_in`: The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour. +- `in_reply_to_conversation_id`: Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`. ## PATCH `/api/v1/update_credentials` @@ -80,6 +100,16 @@ 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 +- `pleroma_settings_store` - Opaque user settings to be saved on the backend. +- `skip_thread_containment` - if true, skip filtering out broken threads +- `pleroma_background_image` - sets the background image of the user. + +### 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. + +This information is returned in the `verify_credentials` endpoint. ## Authentication diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md index 4d99a2d2b..b134b31a8 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` @@ -252,6 +238,21 @@ See [Admin-API](Admin-API.md) ] ``` +## `/api/v1/pleroma/accounts/update_*` +### Set and clear account avatar, banner, and background + +- PATCH `/api/v1/pleroma/accounts/update_avatar`: Set/clear user avatar image +- PATCH `/api/v1/pleroma/accounts/update_banner`: Set/clear user banner image +- PATCH `/api/v1/pleroma/accounts/update_background`: Set/clear user background image + +## `/api/v1/pleroma/accounts/confirmation_resend` +### Resend confirmation email +* Method `POST` +* Params: + * `email`: email of that needs to be verified +* Authentication: not required +* Response: 204 No Content + ## `/api/v1/pleroma/mascot` ### Gets user mascot image * Method `GET` @@ -318,3 +319,38 @@ See [Admin-API](Admin-API.md) "healthy": true # Instance state } ``` + +# Pleroma Conversations + +Pleroma Conversations have the same general structure that Mastodon Conversations have. The behavior differs in the following ways when using these endpoints: + +1. Pleroma Conversations never add or remove recipients, unless explicitly changed by the user. +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. + +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. + + +## `GET /api/v1/pleroma/conversations/:id/statuses` +### Timeline for a given conversation +* Method `GET` +* Authentication: required +* Params: Like other timelines +* Response: JSON, statuses (200 - healthy, 503 unhealthy). + +## `GET /api/v1/pleroma/conversations/:id` +### The conversation with the given ID. +* Method `GET` +* Authentication: required +* Params: None +* Response: JSON, statuses (200 - healthy, 503 unhealthy). + +## `PATCH /api/v1/pleroma/conversations/:id` +### Update a conversation. Used to change the set of recipients. +* Method `PATCH` +* Authentication: required +* Params: + * `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) |