diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/admin_api.md | 277 | ||||
| -rw-r--r-- | docs/api/differences_in_mastoapi_responses.md | 82 | ||||
| -rw-r--r-- | docs/api/pleroma_api.md | 272 | ||||
| -rw-r--r-- | docs/api/prometheus.md | 22 |
4 files changed, 653 insertions, 0 deletions
diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md new file mode 100644 index 000000000..8befa8ea0 --- /dev/null +++ b/docs/api/admin_api.md @@ -0,0 +1,277 @@ +# Admin API + +Authentication is required and the user must be an admin. + +## `/api/pleroma/admin/users` + +### List users + +- Method `GET` +- Query Params: + - *optional* `query`: **string** search term + - *optional* `filters`: **string** comma-separated string of filters: + - `local`: only local users + - `external`: only external users + - `active`: only active users + - `deactivated`: only deactivated users + - *optional* `page`: **integer** page number + - *optional* `page_size`: **integer** number of users per page (default is `50`) +- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10` +- Response: + +```JSON +{ + "page_size": integer, + "count": integer, + "users": [ + { + "deactivated": bool, + "id": integer, + "nickname": string, + "roles": { + "admin": bool, + "moderator": bool + }, + "local": bool, + "tags": array + }, + ... + ] +} +``` + +## `/api/pleroma/admin/user` + +### Remove a user + +- Method `DELETE` +- Params: + - `nickname` +- Response: User’s nickname + +### Create a user + +- Method: `POST` +- Params: + - `nickname` + - `email` + - `password` +- Response: User’s nickname + +## `/api/pleroma/admin/user/follow` +### Make a user follow another user + +- Methods: `POST` +- Params: + - `follower`: The nickname of the follower + - `followed`: The nickname of the followed +- Response: + - "ok" + +## `/api/pleroma/admin/user/unfollow` +### Make a user unfollow another user + +- Methods: `POST` +- Params: + - `follower`: The nickname of the follower + - `followed`: The nickname of the followed +- Response: + - "ok" + +## `/api/pleroma/admin/users/:nickname/toggle_activation` + +### Toggle user activation + +- Method: `PATCH` +- Params: + - `nickname` +- Response: User’s object + +```JSON +{ + "deactivated": bool, + "id": integer, + "nickname": string +} +``` + +## `/api/pleroma/admin/users/tag` + +### Tag a list of users + +- Method: `PUT` +- Params: + - `nickname` + - `tags` + +### Untag a list of users + +- Method: `DELETE` +- Params: + - `nickname` + - `tags` + +## `/api/pleroma/admin/permission_group/:nickname` + +### Get user user permission groups membership + +- Method: `GET` +- Params: none +- Response: + +```JSON +{ + "is_moderator": bool, + "is_admin": bool +} +``` + +## `/api/pleroma/admin/permission_group/:nickname/: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: + +```JSON +{ + "is_moderator": bool, + "is_admin": bool +} +``` + +### Add user in permission group + +- Method: `POST` +- Params: none +- Response: + - On failure: `{"error": "…"}` + - On success: JSON of the `user.info` + +### Remove user from permission group + +- Method: `DELETE` +- Params: none +- Response: + - On failure: `{"error": "…"}` + - On success: JSON of the `user.info` +- Note: An admin cannot revoke their own admin status. + +## `/api/pleroma/admin/activation_status/:nickname` + +### Active or deactivate a user + +- Method: `PUT` +- Params: + - `nickname` + - `status` BOOLEAN field, false value means deactivation. + +## `/api/pleroma/admin/users/:nickname` + +### Retrive the details of a user + +- Method: `GET` +- Params: + - `nickname` +- Response: + - On failure: `Not found` + - On success: JSON of the user + +## `/api/pleroma/admin/relay` + +### Follow a Relay + +- Methods: `POST` +- Params: + - `relay_url` +- Response: + - On success: URL of the followed relay + +### Unfollow a Relay + +- Methods: `DELETE` +- Params: + - `relay_url` +- Response: + - On success: URL of the unfollowed relay + +## `/api/pleroma/admin/invite_token` + +### Get an account registration invite token + +- Methods: `GET` +- Params: + - *optional* `invite` => [ + - *optional* `max_use` (integer) + - *optional* `expires_at` (date string e.g. "2019-04-07") + ] +- Response: invite token (base64 string) + +## `/api/pleroma/admin/invites` + +### Get a list of generated invites + +- Methods: `GET` +- Params: none +- Response: + +```JSON +{ + + "invites": [ + { + "id": integer, + "token": string, + "used": boolean, + "expires_at": date, + "uses": integer, + "max_use": integer, + "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) + }, + ... + ] +} +``` + +## `/api/pleroma/admin/revoke_invite` + +### Revoke invite by token + +- Methods: `POST` +- Params: + - `token` +- Response: + +```JSON +{ + "id": integer, + "token": string, + "used": boolean, + "expires_at": date, + "uses": integer, + "max_use": integer, + "invite_type": string (possible values: `one_time`, `reusable`, `date_limited`, `reusable_date_limited`) + +} +``` + + +## `/api/pleroma/admin/email_invite` + +### Sends registration invite via email + +- Methods: `POST` +- Params: + - `email` + - `name`, optional + +## `/api/pleroma/admin/password_reset` + +### Get a password reset token for a given nickname + +- Methods: `GET` +- Params: none +- Response: password reset token (base64 string) diff --git a/docs/api/differences_in_mastoapi_responses.md b/docs/api/differences_in_mastoapi_responses.md new file mode 100644 index 000000000..1350ace43 --- /dev/null +++ b/docs/api/differences_in_mastoapi_responses.md @@ -0,0 +1,82 @@ +# Differences in Mastodon API responses from vanilla Mastodon + +A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance` + +## Flake IDs + +Pleroma uses 128-bit ids as opposed to Mastodon's 64 bits. However just like Mastodon's ids they are sortable strings + +## Attachment cap + +Some apps operate under the assumption that no more than 4 attachments can be returned or uploaded. Pleroma however does not enforce any limits on attachment count neither when returning the status object nor when posting. + +## Timelines + +Adding the parameter `with_muted=true` to the timeline queries will also return activities by muted (not by blocked!) users. + +## Statuses + +Has these additional fields under the `pleroma` object: + +- `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` + +## Attachments + +Has these additional fields under the `pleroma` object: + +- `mime_type`: mime type of the attachment. + +## 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. + +Has these additional fields under the `pleroma` object: + +- `tags`: Lists an array of tags for the user +- `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/api/entities/#relationship +- `is_moderator`: boolean, nullable, true if user is a moderator +- `is_admin`: boolean, nullable, true if user is an admin +- `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 + +### Source + +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 + +## Account Search + +Behavior has changed: + +- `/api/v1/accounts/search`: Does not require authentication + +## Notifications + +Has these additional fields under the `pleroma` object: + +- `is_seen`: true if the notification was read by the user + +## POST `/api/v1/statuses` + +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. + +## PATCH `/api/v1/update_credentials` + +Additional parameters can be added to the JSON body/Form data: + +- `no_rich_text` - if true, html tags are stripped from all statuses requested from the API +- `hide_followers` - if true, user's followers will be hidden +- `hide_follows` - if true, user's follows will be hidden +- `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 diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md new file mode 100644 index 000000000..190846de9 --- /dev/null +++ b/docs/api/pleroma_api.md @@ -0,0 +1,272 @@ +# Pleroma API + +Requests that require it can be authenticated with [an OAuth token](https://tools.ietf.org/html/rfc6749), the `_pleroma_key` cookie, or [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization). + +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` +### Lists the custom emoji on that server. +* Method: `GET` +* Authentication: not required +* Params: none +* Response: JSON +* Example response: +```json +{ + "girlpower": { + "tags": [ + "Finmoji" + ], + "image_url": "/finmoji/128px/girlpower-128.png" + }, + "education": { + "tags": [ + "Finmoji" + ], + "image_url": "/finmoji/128px/education-128.png" + }, + "finnishlove": { + "tags": [ + "Finmoji" + ], + "image_url": "/finmoji/128px/finnishlove-128.png" + } +} +``` +* Note: Same data as Mastodon API’s `/api/v1/custom_emojis` but in a different format + +## `/api/pleroma/follow_import` +### Imports your follows, for example from a Mastodon CSV file. +* Method: `POST` +* Authentication: required +* Params: + * `list`: STRING or FILE containing a whitespace-separated list of accounts to follow +* Response: HTTP 200 on success, 500 on error +* Note: Users that can't be followed are silently skipped. + +## `/api/pleroma/captcha` +### Get a new captcha +* Method: `GET` +* Authentication: not required +* Params: none +* Response: Provider specific JSON, the only guaranteed parameter is `type` +* Example response: `{"type": "kocaptcha", "token": "whatever", "url": "https://captcha.kotobank.ch/endpoint"}` + +## `/api/pleroma/delete_account` +### Delete an account +* Method `POST` +* Authentication: required +* Params: + * `password`: user's password +* Response: JSON. Returns `{"status": "success"}` if the deletion was successful, `{"error": "[error message]"}` otherwise +* Example response: `{"error": "Invalid password."}` + +## `/api/account/register` +### Register a new user +* Method `POST` +* Authentication: not required +* Params: + * `nickname` + * `fullname` + * `bio` + * `email` + * `password` + * `confirm` + * `captcha_solution`: optional, contains provider-specific captcha solution, + * `captcha_token`: optional, contains provider-specific captcha token + * `token`: invite token required when the registrations aren't public. +* Response: JSON. Returns a user object on success, otherwise returns `{"error": "error_msg"}` +* Example response: +```json +{ + "background_image": null, + "cover_photo": "https://pleroma.soykaf.com/images/banner.png", + "created_at": "Tue Dec 18 16:55:56 +0000 2018", + "default_scope": "public", + "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nぷれろまの生徒会長。謎の外人。日本語OK. \n公主病.", + "description_html": "blushy-crushy fediverse idol + pleroma dev.<br />let's be friends <br />ぷれろまの生徒会長。謎の外人。日本語OK. <br />公主病.", + "favourites_count": 0, + "fields": [], + "followers_count": 0, + "following": false, + "follows_you": false, + "friends_count": 0, + "id": 6, + "is_local": true, + "locked": false, + "name": "lain", + "name_html": "lain", + "no_rich_text": false, + "pleroma": { + "tags": [] + }, + "profile_image_url": "https://pleroma.soykaf.com/images/avi.png", + "profile_image_url_https": "https://pleroma.soykaf.com/images/avi.png", + "profile_image_url_original": "https://pleroma.soykaf.com/images/avi.png", + "profile_image_url_profile_size": "https://pleroma.soykaf.com/images/avi.png", + "rights": { + "delete_others_notice": false + }, + "screen_name": "lain", + "statuses_count": 0, + "statusnet_blocking": false, + "statusnet_profile_url": "https://pleroma.soykaf.com/users/lain" +} +``` + +## `/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` +* Authentication: required +* Params: + * `id`: notification's id +* Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}` + +## `/api/v1/pleroma/accounts/:id/subscribe` +### Subscribe to receive notifications for all statuses posted by a user +* Method `POST` +* Authentication: required +* Params: + * `id`: account id to subscribe to +* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}` +* Example response: +```json +{ + "id": "abcdefg", + "following": true, + "followed_by": false, + "blocking": false, + "muting": false, + "muting_notifications": false, + "subscribing": true, + "requested": false, + "domain_blocking": false, + "showing_reblogs": true, + "endorsed": false +} +``` + +## `/api/v1/pleroma/accounts/:id/unsubscribe` +### Unsubscribe to stop receiving notifications from user statuses +* Method `POST` +* Authentication: required +* Params: + * `id`: account id to unsubscribe from +* Response: JSON, returns a mastodon relationship object on success, otherwise returns `{"error": "error_msg"}` +* Example response: +```json +{ + "id": "abcdefg", + "following": true, + "followed_by": false, + "blocking": false, + "muting": false, + "muting_notifications": false, + "subscribing": false, + "requested": false, + "domain_blocking": false, + "showing_reblogs": true, + "endorsed": false +} +``` + +## `/api/v1/pleroma/accounts/:id/favourites` +### Returns favorites timeline of any user +* Method `GET` +* Authentication: not required +* Params: + * `id`: the id of the account for whom to return results + * `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: JSON, returns a list of Mastodon Status entities on success, otherwise returns `{"error": "error_msg"}` +* Example response: +```json +[ + { + "account": { + "id": "9hptFmUF3ztxYh3Svg", + "url": "https://pleroma.example.org/users/nick2", + "username": "nick2", + ... + }, + "application": {"name": "Web", "website": null}, + "bookmarked": false, + "card": null, + "content": "This is :moominmamma: note 0", + "created_at": "2019-04-15T15:42:15.000Z", + "emojis": [], + "favourited": false, + "favourites_count": 1, + "id": "9hptFmVJ02khbzYJaS", + "in_reply_to_account_id": null, + "in_reply_to_id": null, + "language": null, + "media_attachments": [], + "mentions": [], + "muted": false, + "pinned": false, + "pleroma": { + "content": {"text/plain": "This is :moominmamma: note 0"}, + "conversation_id": 13679, + "local": true, + "spoiler_text": {"text/plain": "2hu"} + }, + "reblog": null, + "reblogged": false, + "reblogs_count": 0, + "replies_count": 0, + "sensitive": false, + "spoiler_text": "2hu", + "tags": [{"name": "2hu", "url": "/tag/2hu"}], + "uri": "https://pleroma.example.org/objects/198ed2a1-7912-4482-b559-244a0369e984", + "url": "https://pleroma.example.org/notice/9hptFmVJ02khbzYJaS", + "visibility": "public" + } +] +``` + +## `/api/pleroma/notification_settings` +### Updates user notification settings +* Method `PUT` +* Authentication: required +* Params: + * `followers`: BOOLEAN field, receives notifications from followers + * `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 +* Response: JSON. Returns `{"status": "success"}` if the update was successful, otherwise returns `{"error": "error_msg"}` + +## `/api/pleroma/healthcheck` +### Healthcheck endpoint with additional system data. +* Method `GET` +* Authentication: not required +* Params: none +* Response: JSON, statuses (200 - healthy, 503 unhealthy). +* Example response: +```json +{ + "pool_size": 0, # database connection pool + "active": 0, # active processes + "idle": 0, # idle processes + "memory_used": 0.00, # Memory used + "healthy": true # Instance state +} +``` diff --git a/docs/api/prometheus.md b/docs/api/prometheus.md new file mode 100644 index 000000000..19c564e3c --- /dev/null +++ b/docs/api/prometheus.md @@ -0,0 +1,22 @@ +# Prometheus Metrics + +Pleroma includes support for exporting metrics via the [prometheus_ex](https://github.com/deadtrickster/prometheus.ex) library. + +## `/api/pleroma/app_metrics` +### Exports Prometheus application metrics +* Method: `GET` +* Authentication: not required +* Params: none +* Response: JSON + +## Grafana +### Config example +The following is a config example to use with [Grafana](https://grafana.com) + +``` + - job_name: 'beam' + metrics_path: /api/pleroma/app_metrics + scheme: https + static_configs: + - targets: ['pleroma.soykaf.com'] +``` |