X-Git-Url: http://git.squeep.com/?a=blobdiff_plain;ds=sidebyside;f=docs%2Fapi%2Fpleroma_api.md;h=5698e88ac8cdbd44790b48efb126f571ff7b73f0;hb=03ad31328c264a1154b7d3b5697b429452a1e6b0;hp=bd3fcaa5d434912778d6a81ee665d789d6f93e9e;hpb=dfae0050af385786c5799ee886de315f69d36a78;p=akkoma
diff --git a/docs/api/pleroma_api.md b/docs/api/pleroma_api.md
index bd3fcaa5d..5698e88ac 100644
--- a/docs/api/pleroma_api.md
+++ b/docs/api/pleroma_api.md
@@ -10,7 +10,29 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* Authentication: not required
* Params: none
* Response: JSON
-* Example response: `{"kalsarikannit_f":"/finmoji/128px/kalsarikannit_f-128.png","perkele":"/finmoji/128px/perkele-128.png","blobdab":"/emoji/blobdab.png","happiness":"/finmoji/128px/happiness-128.png"}`
+* 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`
@@ -27,18 +49,27 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* Method: `GET`
* Authentication: not required
* Params: none
-* 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"}`
## `/api/pleroma/delete_account`
### Delete an account
* Method `POST`
* Authentication: required
-* Params:
+* 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/pleroma/disable_account`
+### Disable an account
+* Method `POST`
+* Authentication: required
+* Params:
+ * `password`: user's password
+* Response: JSON. Returns `{"status": "success"}` if the account was successfully disabled, `{"error": "[error message]"}` otherwise
+* Example response: `{"error": "Invalid password."}`
+
## `/api/account/register`
### Register a new user
* Method `POST`
@@ -52,19 +83,16 @@ Request parameters can be passed via [query strings](https://en.wikipedia.org/wi
* `confirm`
* `captcha_solution`: optional, contains provider-specific captcha solution,
* `captcha_token`: optional, contains provider-specific captcha token
- * `token`: invite token required when the registerations aren't public.
+ * `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
-let's be friends
-ã·ããã¾ã®çå¾ä¼é·ãè¬ã®å¤äººãæ¥æ¬èªOK.
-å
¬ä¸»ç
.",
+ "description": "blushy-crushy fediverse idol + pleroma dev\nlet's be friends \nã·ããã¾ã®çå¾ä¼é·ãè¬ã®å¤äººãæ¥æ¬èªOK. \nå
¬ä¸»ç
.",
"description_html": "blushy-crushy fediverse idol + pleroma dev.
let's be friends
ã·ããã¾ã®çå¾ä¼é·ãè¬ã®å¤äººãæ¥æ¬èªOK.
å
¬ä¸»ç
.",
"favourites_count": 0,
"fields": [],
@@ -98,24 +126,196 @@ let's be friends
## `/api/pleroma/admin/`â¦
See [Admin-API](Admin-API.md)
-## `/api/v1/pleroma/flavour/:flavour`
+## `/api/pleroma/notifications/read`
+### Mark a single notification as read
* 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
+* Params:
+ * `id`: notification's id
+* Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
-## `/api/v1/pleroma/flavour`
-* Method `GET`
+## `/api/v1/pleroma/accounts/:id/subscribe`
+### Subscribe to receive notifications for all statuses posted by a user
+* Method `POST`
* 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
+* 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/pleroma/notifications/read`
-### Mark a single notification as read
+## `/api/v1/pleroma/accounts/:id/unsubscribe`
+### Unsubscribe to stop receiving notifications from user statuses
* Method `POST`
* Authentication: required
* Params:
- * `id`: notifications's id
-* Response: JSON. Returns `{"status": "success"}` if the reading was successful, otherwise returns `{"error": "error_msg"}`
+ * `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/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`
+* Authentication: required
+
+* Response: JSON. Returns a mastodon media attachment entity.
+* Example response:
+```json
+{
+ "id": "abcdefg",
+ "url": "https://pleroma.example.org/media/abcdefg.png",
+ "type": "image",
+ "pleroma": {
+ "mime_type": "image/png"
+ }
+}
+```
+
+### Updates user mascot image
+* Method `PUT`
+* Authentication: required
+* Params:
+ * `image`: Multipart image
+* Response: JSON. Returns a mastodon media attachment entity
+ when successful, otherwise returns HTTP 415 `{"error": "error_msg"}`
+* Example response:
+```json
+{
+ "id": "abcdefg",
+ "url": "https://pleroma.example.org/media/abcdefg.png",
+ "type": "image",
+ "pleroma": {
+ "mime_type": "image/png"
+ }
+}
+```
+* 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`.
+
+## `/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
+}
+```