aboutsummaryrefslogtreecommitdiff
path: root/docs/API
diff options
context:
space:
mode:
Diffstat (limited to 'docs/API')
-rw-r--r--docs/API/admin_api.md220
-rw-r--r--docs/API/differences_in_mastoapi_responses.md9
-rw-r--r--docs/API/pleroma_api.md33
3 files changed, 177 insertions, 85 deletions
diff --git a/docs/API/admin_api.md b/docs/API/admin_api.md
index c042b08ac..2cac317de 100644
--- a/docs/API/admin_api.md
+++ b/docs/API/admin_api.md
@@ -2,11 +2,10 @@
Authentication is required and the user must be an admin.
-## `/api/pleroma/admin/users`
+## `GET /api/pleroma/admin/users`
### List users
-- Method `GET`
- Query Params:
- *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain)
- *optional* `filters`: **string** comma-separated string of filters:
@@ -51,7 +50,6 @@ Authentication is required and the user must be an admin.
### Remove a user
-- Method `DELETE`
- Params:
- `nickname`
- Response: User’s nickname
@@ -60,7 +58,6 @@ Authentication is required and the user must be an admin.
### Remove a user
-- Method `DELETE`
- Params:
- `nicknames`
- Response: Array of user nicknames
@@ -78,31 +75,30 @@ Authentication is required and the user must be an admin.
]
- Response: User’s nickname
-## `/api/pleroma/admin/users/follow`
+## `POST /api/pleroma/admin/users/follow`
+
### Make a user follow another user
-- Methods: `POST`
- Params:
- - `follower`: The nickname of the follower
- - `followed`: The nickname of the followed
+ - `follower`: The nickname of the follower
+ - `followed`: The nickname of the followed
- Response:
- - "ok"
+ - "ok"
+
+## `POST /api/pleroma/admin/users/unfollow`
-## `/api/pleroma/admin/users/unfollow`
### Make a user unfollow another user
-- Methods: `POST`
- Params:
- - `follower`: The nickname of the follower
- - `followed`: The nickname of the followed
+ - `follower`: The nickname of the follower
+ - `followed`: The nickname of the followed
- Response:
- - "ok"
+ - "ok"
-## `/api/pleroma/admin/users/:nickname/toggle_activation`
+## `PATCH /api/pleroma/admin/users/:nickname/toggle_activation`
### Toggle user activation
-- Method: `PATCH`
- Params:
- `nickname`
- Response: User’s object
@@ -115,27 +111,26 @@ Authentication is required and the user must be an admin.
}
```
-## `/api/pleroma/admin/users/tag`
+## `PUT /api/pleroma/admin/users/tag`
### Tag a list of users
-- Method: `PUT`
- Params:
- `nicknames` (array)
- `tags` (array)
+## `DELETE /api/pleroma/admin/users/tag`
+
### Untag a list of users
-- Method: `DELETE`
- Params:
- `nicknames` (array)
- `tags` (array)
-## `/api/pleroma/admin/users/:nickname/permission_group`
+## `GET /api/pleroma/admin/users/:nickname/permission_group`
### Get user user permission groups membership
-- Method: `GET`
- Params: none
- Response:
@@ -146,13 +141,12 @@ Authentication is required and the user must be an admin.
}
```
-## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group`
+## `GET /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.
### Get user user permission groups membership per permission group
-- Method: `GET`
- Params: none
- Response:
@@ -184,6 +178,8 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
## DEPRECATED `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
+## `DELETE /api/pleroma/admin/users/:nickname/permission_group/:permission_group`
+
### Remove user from permission group
- Params: none
@@ -239,30 +235,20 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
}
```
-## DEPRECATED `PATCH /api/pleroma/admin/users/:nickname/activation_status`
-
-### Active or deactivate a user
-
-- Params:
- - `nickname`
- - `status` BOOLEAN field, false value means deactivation.
-
-## `/api/pleroma/admin/users/:nickname_or_id`
+## `GET /api/pleroma/admin/users/:nickname_or_id`
### Retrive the details of a user
-- Method: `GET`
- Params:
- `nickname` or `id`
- Response:
- On failure: `Not found`
- On success: JSON of the user
-## `/api/pleroma/admin/users/:nickname_or_id/statuses`
+## `GET /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`)
@@ -271,19 +257,19 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- On failure: `Not found`
- On success: JSON array of user's latest statuses
-## `/api/pleroma/admin/relay`
+## `POST /api/pleroma/admin/relay`
### Follow a Relay
-- Methods: `POST`
- Params:
- `relay_url`
- Response:
- On success: URL of the followed relay
+## `DELETE /api/pleroma/admin/relay`
+
### Unfollow a Relay
-- Methods: `DELETE`
- Params:
- `relay_url`
- Response:
@@ -297,11 +283,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- Response:
- On success: JSON array of relays
-## `/api/pleroma/admin/users/invite_token`
+## `POST /api/pleroma/admin/users/invite_token`
### Create an account registration invite token
-- Methods: `POST`
- Params:
- *optional* `max_use` (integer)
- *optional* `expires_at` (date string e.g. "2019-04-07")
@@ -319,11 +304,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
}
```
-## `/api/pleroma/admin/users/invites`
+## `GET /api/pleroma/admin/users/invites`
### Get a list of generated invites
-- Methods: `GET`
- Params: none
- Response:
@@ -345,11 +329,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
}
```
-## `/api/pleroma/admin/users/revoke_invite`
+## `POST /api/pleroma/admin/users/revoke_invite`
### Revoke invite by token
-- Methods: `POST`
- Params:
- `token`
- Response:
@@ -367,21 +350,18 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
}
```
-
-## `/api/pleroma/admin/users/email_invite`
+## `POST /api/pleroma/admin/users/email_invite`
### Sends registration invite via email
-- Methods: `POST`
- Params:
- `email`
- `name`, optional
-## `/api/pleroma/admin/users/:nickname/password_reset`
+## `GET /api/pleroma/admin/users/:nickname/password_reset`
### Get a password reset token for a given nickname
-- Methods: `GET`
- Params: none
- Response:
@@ -392,18 +372,18 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
}
```
-## `/api/pleroma/admin/users/force_password_reset`
+## `PATCH /api/pleroma/admin/users/force_password_reset`
### Force passord reset for a user with a given nickname
-- Methods: `PATCH`
- Params:
- `nicknames`
- Response: none (code `204`)
-## `/api/pleroma/admin/reports`
+## `GET /api/pleroma/admin/reports`
+
### Get a list of reports
-- Method `GET`
+
- Params:
- *optional* `state`: **string** the state of reports. Valid values are `open`, `closed` and `resolved`
- *optional* `limit`: **integer** the number of records to retrieve
@@ -418,7 +398,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
```json
{
- "total" : 1,
+ "totalReports" : 1,
"reports": [
{
"account": {
@@ -560,9 +540,34 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
}
```
-## `/api/pleroma/admin/reports/:id`
+## `GET /api/pleroma/admin/grouped_reports`
+
+### Get a list of reports, grouped by status
+
+- Params: none
+- On success: JSON, returns a list of reports, where:
+ - `date`: date of the latest report
+ - `account`: the user who has been reported (see `/api/pleroma/admin/reports` for reference)
+ - `status`: reported status (see `/api/pleroma/admin/reports` for reference)
+ - `actors`: users who had reported this status (see `/api/pleroma/admin/reports` for reference)
+ - `reports`: reports (see `/api/pleroma/admin/reports` for reference)
+
+```json
+ "reports": [
+ {
+ "date": "2019-10-07T12:31:39.615149Z",
+ "account": { ... },
+ "status": { ... },
+ "actors": [{ ... }, { ... }],
+ "reports": [{ ... }]
+ }
+ ]
+```
+
+## `GET /api/pleroma/admin/reports/:id`
+
### Get an individual report
-- Method `GET`
+
- Params:
- `id`
- Response:
@@ -571,22 +576,41 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- 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`
+## `PATCH /api/pleroma/admin/reports`
+
+### Change the state of one or multiple reports
+
- Params:
- - `id`
- - `state`: required, the new state. Valid values are `open`, `closed` and `resolved`
+
+```json
+ `reports`: [
+ {
+ `id`, // required, report 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)
+ - 400 Bad Request, JSON:
+
+ ```json
+ [
+ {
+ `id`, // report id
+ `error` // error message
+ }
+ ]
+ ```
+
+ - On success: `204`, empty response
+
+## `POST /api/pleroma/admin/reports/:id/respond`
-## `/api/pleroma/admin/reports/:id/respond`
### Respond to a report
-- Method `POST`
+
- Params:
- `id`
- `status`: required, the message
@@ -656,9 +680,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
}
```
-## `/api/pleroma/admin/statuses/:id`
+## `PUT /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`
@@ -670,9 +695,10 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- 404 Not Found `"Not found"`
- On success: JSON, Mastodon Status entity
-## `/api/pleroma/admin/statuses/:id`
+## `DELETE /api/pleroma/admin/statuses/:id`
+
### Delete an individual reported status
-- Method `DELETE`
+
- Params:
- `id`
- Response:
@@ -681,11 +707,12 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret
- 404 Not Found `"Not found"`
- On success: 200 OK `{}`
+## `GET /api/pleroma/admin/config/migrate_to_db`
-## `/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:
@@ -693,10 +720,12 @@ Copy settings on key `:pleroma` to DB.
{}
```
-## `/api/pleroma/admin/config/migrate_from_db`
+## `GET /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:
@@ -704,10 +733,12 @@ Copy all settings from DB to `config/prod.exported_from_db.secret.exs` with dele
{}
```
-## `/api/pleroma/admin/config`
+## `GET /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:
@@ -723,8 +754,10 @@ List config settings only works with `:pleroma => :instance => :dynamic_configur
}
```
-## `/api/pleroma/admin/config`
+## `POST /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"`.
@@ -747,7 +780,6 @@ Compile time settings (need instance reboot):
- `Pleroma.Upload` -> `:proxy_remote`
- `:instance` -> `:upload_limit`
-- Method `POST`
- Params:
- `configs` => [
- `group` (string)
@@ -802,9 +834,10 @@ Compile time settings (need instance reboot):
}
```
-## `/api/pleroma/admin/moderation_log`
+## `GET /api/pleroma/admin/moderation_log`
+
### Get moderation log
-- Method `GET`
+
- Params:
- *optional* `page`: **integer** page number
- *optional* `page_size`: **integer** number of log entries per page (default is `50`)
@@ -831,8 +864,25 @@ Compile time settings (need instance reboot):
```
## `POST /api/pleroma/admin/reload_emoji`
+
### Reload the instance's custom emoji
-* Method `POST`
-* Authentication: required
-* Params: None
-* Response: JSON, "ok" and 200 status
+
+- Authentication: required
+- Params: None
+- Response: JSON, "ok" and 200 status
+
+## `PATCH /api/pleroma/admin/users/confirm_email`
+
+### Confirm users' emails
+
+- Params:
+ - `nicknames`
+- Response: Array of user nicknames
+
+## `PATCH /api/pleroma/admin/users/resend_confirmation_email`
+
+### Resend confirmation email
+
+- Params:
+ - `nicknames`
+- Response: Array of user nicknames
diff --git a/docs/API/differences_in_mastoapi_responses.md b/docs/API/differences_in_mastoapi_responses.md
index 7fbe17130..566789ec7 100644
--- a/docs/API/differences_in_mastoapi_responses.md
+++ b/docs/API/differences_in_mastoapi_responses.md
@@ -57,6 +57,7 @@ Has these additional fields under the `pleroma` object:
- `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
+- `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.
### Source
@@ -91,11 +92,18 @@ Has these additional fields under the `pleroma` object:
- `is_seen`: true if the notification was read by the user
+### Move Notification
+
+The `type` value is `move`. Has an additional field:
+
+- `target`: new account
+
## GET `/api/v1/notifications`
Accepts additional parameters:
- `exclude_visibilities`: will exclude the notifications for activities with the given visibilities. The parameter accepts an array of visibility types (`public`, `unlisted`, `private`, `direct`). Usage example: `GET /api/v1/notifications?exclude_visibilities[]=direct&exclude_visibilities[]=private`.
+- `with_move`: boolean, when set to `true` will include Move notifications. `false` by default.
## POST `/api/v1/statuses`
@@ -136,6 +144,7 @@ Additional parameters can be added to the JSON body/Form data:
- `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
+- `allow_following_move` - if true, allows automatically follow moved following accounts
- `pleroma_background_image` - sets the background image of the user.
### Pleroma Settings Store
diff --git a/docs/API/pleroma_api.md b/docs/API/pleroma_api.md
index 6c326dc9b..7228d805b 100644
--- a/docs/API/pleroma_api.md
+++ b/docs/API/pleroma_api.md
@@ -302,6 +302,7 @@ See [Admin-API](admin_api.md)
* `follows`: BOOLEAN field, receives notifications from people the user follows
* `remote`: BOOLEAN field, receives notifications from people on remote instances
* `local`: BOOLEAN field, receives notifications from people on the local instance
+ * `privacy_option`: 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"}`
## `/api/pleroma/healthcheck`
@@ -479,3 +480,35 @@ The status posting endpoint takes an additional parameter, `in_reply_to_conversa
* `artist`: the artist of the media playing [optional]
* `length`: the length of the media playing [optional]
* Response: the newly created media metadata entity representing the Listen activity
+
+# Emoji Reactions
+
+Emoji reactions work a lot like favourites do. They make it possible to react to a post with a single emoji character.
+
+## `POST /api/v1/pleroma/statuses/:id/react_with_emoji`
+### React to a post with a unicode emoji
+* Method: `POST`
+* Authentication: required
+* Params: `emoji`: A single character unicode emoji
+* Response: JSON, the status.
+
+## `POST /api/v1/pleroma/statuses/:id/unreact_with_emoji`
+### Remove a reaction to a post with a unicode emoji
+* Method: `POST`
+* Authentication: required
+* Params: `emoji`: A single character unicode emoji
+* Response: JSON, the status.
+
+## `GET /api/v1/pleroma/statuses/:id/emoji_reactions_by`
+### Get an object of emoji to account mappings with accounts that reacted to the post
+* Method: `GET`
+* Authentication: optional
+* Params: None
+* Response: JSON, a map of emoji to account list mappings.
+* Example Response:
+```json
+{
+ "😀" => [{"id" => "xyz.."...}, {"id" => "zyx..."}],
+ "🗡" => [{"id" => "abc..."}]
+}
+```
generated by cgit v1.2.3 (git 2.26.2) at 2025-04-26 21:00:24 +0000